Take that Apple…
{February 5, 2008} #85
{January 29, 2008} #72
10 golden rules of Technical Writing
1. Get to the point as clearly and distinctly as possible (ie. No flowery prose; it’s information not marketing material). Short and Sweet Keeps It Neat (SSKIN)
2. Procedural material is structured thus: Task, Location, Operation (eg. To create a message, in the Gmail window, click Compose Mail).
3. If it’s Online you don’t stick a bazillion screenshots inamongst the procedures; it’s distracting and makes the thing hard to read. If it’s print docs, then you’ll have to compromise.
4. Try, whereever possible, to separate explanations of windows from the procedures to operate them, this way procedures can be used to construct complete tasks.
5. What’s a Task, you ask? A Task is a collection of procedures which occur throughout an application or programme to achieve a particular goal. (eg. To send a message in Gmail, you don’t just jump in with “Click Compose Mail”. You have to first open the site, then logon, then Compose Mail; 3 procedures in all).
6. No UI, No Documentation, it’s that simple. It is ultimately impossible to construct accurate documentation unless you’ve got the User Interface. Those that say you can are idiots. The logic is simple: they think their specifications are perfect and will be translated directly in to the programme. The truth is that the specifications are rarely translated in an identical manner. Therefore lots of time can be lost documenting from Specs, then re-jigged when the actual application comes through. Also, specifications are far too complicated and often include useless information.
7. Know Your Audience. Users don’t care that the application is written in Perl with PHP5 and a SQL-Server 2003 back-end database, therefore don’t add such technical jiggery-pokery to user documents. Technical documents, however, probably need information like this.
8. I forget what 8 was for.
9. Hardcore knowledge of databases, programming languages, test-scripting and anything else are not required to write documentation about a programmes. They can help but are more likely to complicate issues
10. It’s always nice to have a Table of Definitions/Terms somewhere in the docs, to cover-off all those annoying acronyms.
{January 21, 2008} #58
Thanks to Man-In-Black for this one 
{January 20, 2008} #54
And your starter for ten, what is the first image of, which sci-fi series was it in, and which episode?
For extra points, what was the original planet from which the ships came from?
