Having just-about-finished the coding for version 1.0 of SubTracker, I'm embarking upon its documentation. I can remember some time ago, when I first considered technical writing as a day-job (and again, not that long ago when I began my contract) I shuddered at the terrible question of how do you actually write a technical document? Where do you start? What goes in it? How do you make sure you get everything? What mysterious tasks are you expected to do besides from give people a document about their software? It's not as daunting as it looks, even for megolithic software packages. 

Step one: Planning

You're approached by a client who wants their software documented. Say they want some online help, and a physical manual, as well as "some training materials" (clients are wonderfully vague at times). You'll list briefly what you can offer (example: maybe you're a web-guru, who can make online-self-test training packages, or a training-video-nut, or maybe you're better off with a secondary training manual.) Assuming the client likes what they hear, you'll be asked for a quote, and given a copy of the software to play with. (Occasionally, they'll give you the software specs instead, which is much less helpful. If you can, always try to get a copy of the software).

Quotes are calculated on a per-page basis - usually, three hours per page. To know what to quote them, you're going to need to know how many pages you'll be writing. Which is where 'planning' comes into it:

Pre-planning stage:

1. Spend some time with the software - familiarise yourself with what its purpose is, read the release notes (if any). If necessary, do some research on the subjects that the software deals with.
2. If the program can be clearly separated into parts or components, write these on separate sheets of paper. (If it can't, just skip this step; we'll organise at the end.)
3. Start in one corner of the screen, (Usually "File > New..." ) open the menus one at a time, and write down everything you can do with the software. Even if it's obvious, like closing a file. If you have pages with separate software sections, use the appropriate section for each function, or a 'misc' sheet for functions that don't fit.
4. You'll need to note what screens or windows come up for what tasks, and any tasks you can do from those screens (and any screens that come up from those tasks, etc). Note any shortcuts, hotkeys, or multiple ways that you achieve the same action or access the same window. Note warnings and errors, and what caused them to occur.
5. Note any functionality that isn't accessible from the graphical interface - actions that are only accessable via hotkeys, for example.
6. In a nutshell - you want to note down every single feature that the software does, and a 'map' of how to get to all those features.

Planning stage:

1. Look at your notes. Can you see a structure? If there were clear divisions of components when you started, do those still apply? Is there functionality that doesn't fit within these divisions?
2. If you didn't start with divisions, try grouping the functions into small sections, and then grouping those sections into larger ones. Make sure your sections are sensible; many smaller, self-contained sections is far preferable to fewer but less internally cohesive sections.
3. Take each section and structure it into a logical sequence. Typically, you'll begin with a brief introduction for what this area of the software manages, any terms or phrases that the user needs to know, and give an overview of the main features. Then the procedures, possibly followed by an index if it's a very large section (or you may put the index at the end).
4. It's usually best to group procedures together if they share common graphical interface elements - tasks that you can perform using the same screen. Keep the tasks as discrete procedures, unless their purpose is extremely similar and their procedure only differs by one step. 
5. Decide on an order for the tasks themselves - if there is a clear order implied by the interface design, or by the procedures themselves (perhaps functions A B and C will always have to be done before D, E and F) then use that; otherwise, choose some kind of system (alphabetical is a comon fallback) and stick with it.
6. Structure your other sections accordingly, and then apply the same principles to structure the overall documentation - an introduction, the sections in some kind of consistent and logical order, appendices and indexes.\
7. Type this up so it looks impressive. 

Post planning stage:

1. Count up the number of pages you have. That should be one page per introduction, one per function (or more, if it's a very involved function), one per screen or window (or more, if it's a screen or window with a lot of options or tasks), and one per 20 index entries.
2. Multiply the number of pages by 3 (the standard calculation is 3 hours per page.), and multiply that figure by your hourly rate. This is your negotiation minimum - you can't go below this number without the work actually costing you, rather than earning for you.
3. Add your slack time to the total-pages-times-3 figure. This is the time for things to go wrong, without it costing you. 10 - 20% is typical. Multiply this by your hourly rate again - this is your starting point for negotiations.
4. Divide the pages-times-three-plus-slack-time by the number of hours you will work on the project per week. This is the estimated completion time.
5. Present your quote package - the starting-point price, the estimated completion time, and the projected document structure. Your client will likely negotiate features they do/don't want, cost, time, etc. That's okay - just redo the process from whatever step you need do. If they're adding features, remember to consider all aspects of the software that this feature might affect, and add it to your original notes.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2