Post History

Source: https://writers.stackexchange.com/a/5219
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I'm answering this as a technical writer but I don't have translation experience so can't address any aspects specific to that.

Many of the habits that (I hope) you already have as a software developer apply equally to technical writing:

- Design first: figure out how you will structure the document to cover everything with a good flow (more on that in a minute). Stub it out -- does it work? In your case it sounds like they'll be giving you a rough document so this might not apply as much, but review it for structure/organization first anyway.

- Put yourself in the user's shoes: what _tasks_ will the user be attempting to complete? What does he need to know in order to do that? Don't just "walk the menus" (as is common in application documentation); think about his goals. If you've ever written API documentation and have risen above the level of the individual class/method/function to produce package overviews, developer guides, etc, do the same thing here.

- Work breadth-first, not depth-first: especially because this is a new area for you, there is risk that you'll get bogged down in the early sections and have to rush the end to meet the deadline/time-allocation. Do one reasonable pass over the whole thing using no more than half the time allotted. Then assess where the most work is needed and address that. Save about 20% of the time for an editorial/polishing pass (and to address any comments you receive).

- Ask your questions early: something they've given you won't make sense but you won't spot it early if you don't look. Review everything they've given you first, before you start designing and writing, so you can queue up the questions and go on to other work while waiting for the answers. (This is particularly important if you're looking at at least a one-day turn-around due to time zones.) As with any other work you've done, you don't want to get blocked on everything because you're blocked on something; structure your work to support this kind of multi-tasking.

When will your work be reviewed? Only at the end, or will there be a review of a draft before you're done? If the task is more than a couple of full-time weeks then, especially for a first gig, I would ask for a draft review to make sure everyone agrees about the level of detail, prose quality, structure, etc that you're producing.

Original score: 5