[TUHS] Documentation (was On Bloat and the Idea of Small Specialized Tools)

[Paul Winalski <paul.winalski@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1344 bytes --]

On Mon, May 20, 2024 at 2:08 AM Adam Thornton <athornton@gmail.com> wrote:

> I can't tell you--although some of you will know--what a delight it is to
> be working on a project with an actual documentation engineer.
>
> That person (Jonathan Sick, if any of you want to hire him) has engineered
> things such that it is easy to write good documentation for the projects we
> write, and not very onerous.
>
> Design for documentability, testability, and ease of maintenance are what
distinguishes good software engineering from hackery.

Back when I worked in DEC's software development tools group, we had
professional technical writers who write the manuals and online help text.
There was an unexpected (at least by me) benefit during a project's design
phase, too.  Documentation was written in parallel with the code, so once
the user interface specification was arrived at, first order of business
was to sit down with the tech writer and explain it to them.  Sometimes in
the process of doing that youd stop and think, "wait a minute--we don't
really want it doing that".  Or you'd find that you bhad difficulty
articulating exactly how a particular feature behaves.  That's a red flag
that you've designed the feature to be too obscure and complex, or that
there's something flat-out wrong with it.

-Paul W.

[-- Attachment #2: Type: text/html, Size: 1732 bytes --]