Learning

Writing Instructions

Brent Simmons writes “... it’s good for engineers and architects to write docs because it makes the software better.”

....

Engineers, architects, writers, and others should collaborate on documentation. The collaboration should be based upon engineers and architects serving as subject matter experts for the writer.

....

Engineers can’t do it (at least not for their own projects). They know too much.

[ARTS & FARCES internet]

They're both right. One of the reasons why programmer types don't write good documentation is that they, like someone giving directions to his house, assume too much familiarity on the part of the reader. Writing documentation, and having it used by someone else, reveals the missing steps. It also reveals the way to better software.

Remember that class in BASIC on the TRS-80 in high school? The computer does everything you tell it to, exactly as you say, but if you don't tell it, it can't do it. You cannot skip steps.

11:48:16 AM # Google It!
categories: Learning, Writing Online, System Administration