Archive for June, 2011

h1

What goes into a Project Charter?

June 30, 2011

If you’ve been given the task of setting up a Project Charter document (also known as a ‘Terms of Reference’ document), you might not know where to start.

Here’s a broad outline of the major headings you are likely to need, from the people at Mentoric:

  1. Background
  2. Objectives
  3. Scope
  4. Constraints
  5. Assumptions
  6. Roles and Responsibilities
  7. Key Deliverables

For an expanded list — with subheadings — see this article: http://www.mentoric.com/resource_project_tor.html

[Link last checked June 2011]

h1

Excel: Save a worksheet as an image file

June 29, 2011

You can save an Excel worksheet to several formats, but, surprisingly, you cannot save it — or a selection from it — as an image. I would have thought this simple function would have been an option in Excel 2007 or 2010, but it’s not.

Saving to PDF (and then to an image format) is an option if the worksheet is not particularly wide, but as soon as the worksheet stretches over more than one page, PDF is not suitable unless you want to cobble together several PDF files to make one image.

After trying several methods and searching the internet, I figured out the best way to do it; this method works in Excel 2003, 2007, and 2010:

  1. Select the worksheet cells containing the data, chart, etc. you want to save as an image (turn off grid lines if you don’t want them too).
  2. Copy the selection to the clipboard (Ctrl+C).
  3. Open a graphics editor. My personal preference is SnagIt, but Microsoft Paint works just as well.
  4. Paste the selection into your graphics editor (Ctrl+V).
  5. Save the pasted image as a GIF (suitable for simple line drawings), JPG (suitable for photos only), or PNG (suitable for almost anything).

From my internet searching, it sounds like this is something many people want to do, so it would be good if Microsoft could offer a ‘save as image’ option from Excel.

Aside: Some wit on the internet had this to say about how to save an Excel worksheet as an image:

Take a photograph using your phone, send it to your home email,  then sketch an artist’s impression of said Excel sheet based on the photo content, scan that into your hard drive, send back to work and save it.

Another had this method:

  1. Stick a sheet of tracing paper to your monitor.
  2. Then make a brass rubbing of the Excel table.
  3. Remove the tracing paper and pour plaster of paris over the top.
  4. Cover in spray mount and glitter.
  5. Shake off the excess and voila!

[Link last checked June 2011]

h1

Search limitations

June 28, 2011

There’s absolutely NO technical reason why, in 2011, a search of a website’s database should be limited in the results it displays and in the search terms entered. There are plenty of free and paid search and indexing services that allow full text searches of databases without such limits.

So why does one of the only public sources of Australian music have a really crappy sub-par search? The site is the official site of the Australasian Performing Right Association (APRA) and the Australasian Mechanical Copyright Owners Society (AMCOS), and its search capabilities are frustrating, to say the least.

Here are some examples from some recent searches I tried, highlighting some of the issues I found in the first five minutes. I gave up after that…

Issue 1: You can’t search for a writer without a title or performer

I searched for an Australian songwriter, Ross Wilson, and got this result:

Cannot search for a songwriter alone

Cannot search for a songwriter alone

I got the same result whether I searched for Wilson, Ross, Wilson*, Wilson Ross or Wilson combined with any other name, and with all other songwriter names I tried. So, you have to know a performer or title or a songwriter’s works to be able to find the songwriter in the database. That’s just crazy!

By the way, their own 5-point Help says that I can put in a writer (first point) and doesn’t tell me I have to also enter a title or performer:

APRA/AMCOS Help

APRA/AMCOS Help

Issue 2: Search results are limited to 750

I put in Rolling* as the performer and got this:

Search stops if more than 750 results

Search stops if more than 750 results

But instead of showing me the first 750 results found of these 802, I got no results list at all. With only 802 possible results in this search, there’s a good chance that what I want is in the first 750, so why can’t the system allow me to see those 750? Sure, I got a message about narrowing my search results to get a better result, but let me at least have the option of viewing the 750 found. Better still, show me ALL results and let me decide if there are too many for me to deal with. Google does this all the time with results sets in the millions.

Issue 3: Wildcard searches have a 5-character minimum

This one is just crazy. There are plenty of performers and bands that have fewer than five characters in their name but you cannot search for them using the asterisk wildcard. What if you know one name of a performer but not the other (e.g. you know that one of the first Australian Idol winners was called Guy but you can’t remember his surname)? You can’t search for Guy* without generating an error message:

Five or more characters are required for a wildcard search

Five or more characters are required for a wildcard search

Issue 4: Searches for a 4-character performer take ages

If you enter a four-character performer’s name with no wildcard (e.g. Barb), the search takes forever and eventually you get a 25-item result list. Other searches of longer names or with wildcards generate many more results (or error messages) and are shown in a few seconds. But not when the performer’s name is short.

Issue 5: Symbols in a search term generate an error

There’s no excuse for this one — if non-alphanumeric characters are not acceptable as the first character in a search term, why not have the system strip them out or ignore them? Instead, you get get an error message and have to re-enter your search term:

Non alphanumeric characters aren't stripped from a search term

Non alphanumeric characters aren't stripped from a search term

Interestingly, a Google search for $64000 question came up with this APRA web page, which is NOT found via APRA’s own search: http://www.apra.com.au/cms/Documents/AMCOS_Control_List/AMCOS_ControlList_December2010.txt

 

As I said, I gave up using this database after a few minutes. I didn’t try any sort of Boolean searching as I suspect that would just have raised my blood pressure.

If you’re keen, you can search this database yourself here: https://www.apra.com.au/cms/worksearch/worksearch.srvlt

[Link last checked June 2011]

h1

How the CIA can help technical communicators

June 27, 2011

The CIA? And technical communicators? What the…?

Well, there’s more of a connection than you’d suppose. The ‘Phoenix Questions’, for starters. Although these questions are for training new agents to look at a problem from all angles, the set of questions can be applied to pretty much any problem, project, issue, challenge — or any new documentation effort!

Here’s a snapshot of some of the problem-solving ‘Phoenix Questions’; for the complete list, go to http://www.mentoric.com/resource_phoenix_questions.html

sample Phoenix Questions

sample Phoenix Questions

[Link last checked June 2011]

h1

Word: Dialog Box names for VBA

June 24, 2011

If you’re using VBA in Word, you may need to call or modify a dialog box and its settings.

The problem is finding out what all the dialog boxes are named, and what arguments they can take. Scrolling through a long list in the VBA editor is not for the faint-hearted! And the VBA Help isn’t very helpful.

However, you can find lists of all dialog boxes for Word 2007 and 2010 on the Microsoft website, along with the arguments you can use to get or set values:

If you need to reference these often, print out these lists.

[Links last checked June 2011]

h1

Word: Macros to delete all tables and figures

June 23, 2011

I have NO idea why you might want to do this, but figured I’d share these two macros — one is to delete all tables, and the other is to delete all figures from a Word document.

The macro to delete all tables is from Allen Wyatt’s Word VBA Guidebook (http://store.tips.net/T010353_Word_VBA_Guidebook_Table_of_Contents.html); the one to delete all figures was one I created based on the tables one. However, it wasn’t easy! Unlike tables (Table object), figures aren’t under normal words like ‘figure’, ‘picture’, ‘photo’, ‘diagram’, or ‘image’ — no, they are part of the InlineShape object! That bit of information took some time to find.

Please use with caution — these macros WILL delete every table or figure, except those in your document’s headers and footers.

Macro to delete all tables in a document

Sub TablesDeleteAll()
    Dim tbl As Table
    For Each tbl In ActiveDocument.Tables
        tbl.Delete
    Next tbl
End Sub

Macro to delete all figures in a document

Sub FiguresDeleteAll()
    Dim fig As InlineShape
    For Each fig In ActiveDocument.InlineShapes
        fig.Delete
    Next fig
End Sub

[Links last checked June 2011]

h1

How long to edit a 50-page software manual

June 22, 2011

The question

Here’s the issue as posed by a member of an email discussion list I’m on:

I’m currently conducting a study to determine the average time spent by a Technical Writer/Editor to proofread a technical document. Assume that the document is a 50-page typical technical manual of a PC software. I would appreciate if you could share your estimates for the task.

My answer

It depends… And it depends on a lot of things. The length of the document (50 pages) is only one very tiny factor. Here are some ‘it depends’ questions, in no particular order.

  • What do you mean by ‘proofread’? Just a quick look through for typos, punctuation errors, misspellings, etc.? or a more thorough copyedit (including such items as I list here: https://cybertext.wordpress.com/2011/05/17/copyediting-from-a-copyeditors-perspective/) Do you actually mean a technical edit, where the editor is also verifying the validity of the information against the application? Or a substantive edit where the editor can move sections around for better understanding, more logical flow etc?
  • How big are the document’s pages? An A5 document’s 50 pages is not the same as 50 pages of A4 or A3, for example. So giving us a ballpark figure of a 50-page document is not very useful without knowing the page size.
  • How much text is on each page, versus screen shots, tables, figures etc.? And do all these have to be checked? (For example, I check text on figures/screen shots as well as in tables.)
  • How much of the document is made up of front matter and end matter, and do these elements need to be checked? (e.g. TOC, glossary etc.)
  • Is it assumed that the editor knows anything about the domain/subject matter? Someone without any knowledge of the area is likely to take much longer to edit the document. I would find it very difficult to edit documentation for complex financial software used by banks, whereas editing 3D geological modeling software would be fairly easy for me.
  • Does any software have to be installed by the editor before they can edit the document? If so, are there other things that need to be installed for the software to run (special databases, virtual machines, Java apps, etc.)? Will this installation and configuration time been taken into account in the estimate?
  • How many review cycles are included in the edit? Just because an editor recommends something, doesn’t mean that the author will accept that recommendation and discussions, meetings etc. may need to be factored in.
  • How will the editing be done? Hard copy mark up? Acrobat mark up? Word’s Track Changes? something else?
  • What format is the documentation in, and is that format able to be edited directly? e.g. a CHM is hard to edit directly, whereas a Word document is easy.
  • What’s the state of the writing? Does the author have good command of the language in which they are writing? Is the author experienced in technical writing? As I state in my blog post that I linked to above, a 350-page document from a good author may take as long for me to edit as a 40-page document from an author whose writing needs a lot of editing.
  • How much mechanical stuff does the editor need to fix? Things such as headers, footers, styles, apply a template, add document control tables etc.
  • As far as time goes, are you expecting the editor to do the editing in one session, or spaced out in between their other jobs? Editing is tiring on the eyes, brains, shoulders and neck, and doing it solidly for eight hours at a time is ergonomically unsound.

I’m sure there are many more ‘it depends’ factors, but these are a good starting point in trying to scope out an estimate. There’s no way I could give an estimate based on the original question, but if I found out the answers to the questions above, I’d be in a better position to do so.

Related blog posts:

[Links last checked June 2011; photo from: http://morguefile.com/archive/display/606352]