Writing Tips

1. When you must include specific product names, version numbers, file paths, window names, wizard panes, field-box names etc. that might change during the SDLC, do not hard code them. Use variables.  If writing with DITA, use conrefs; if writing with MS Word, use fields; if writing with any other help authoring tools, use the features that the tool has for handling variable content.



2. When writing a procedure, do not document the workarounds for any step that does not work as designed; do not document bug fixes in procedures.  Write the procedures like they should normally work; write the bug fixes elsewhere (Troubleshooting?) and give a cross-reference in the procedure.  Clean procedures are easier to maintain from release to release; bugs get fixed from release to release and the documented bug fixes can either be updated or retired.
3. If you are going to re-use something, do it from one single location instead of giving in to spaghetti code# and reusing from file A to file B, then to file C, thence to file Q.  If one file in that chain moves elsewhere or ceases to exist, the whole link breaks; besides, it is easier to keep sight of a fixed target than a moving one.

# Spaghetti code is a pejorative term for source code that has a complex and tangled control structure, just like a dish of spaghetti.

About the author:

Anindita Basu is a writer and editor at IBM. She can be reached at anindita_basu@shortmail.com. Illustrations are courtesy www.makebeliefscomix.com.