- 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.
- 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.
- 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 email@example.com. Illustrations are courtesy www.makebeliefscomix.com.