Roman Suzi
2 min readNov 24, 2019

--

Excellent write up! I’d only added that I see (user-facing) documentation as part of several processes. For example, “technical writer” (and translators) can participate in testing the feature to understand the context. Then developers are not only “chased” by the “writer”: They receive direct feedback on the quality. possible UX issues, and even so far unnoticed bugs.

Another process is support (user support or internal support — for instance, sales). If the process is organized carefully, answers are cached (in the form of FAQ, but may also be in some other forms).

New release features can also grow from version control commit messages and/or changelog entries. That is, if developers are accustomed to write those from the user point of view, not system internals.

As for docstrings, code comments, etc — modern methodologies frown upon writing them all the time. There some documentation generator tools to build nice developer documentation, but personally I do not see much value in that beyond generating API documentation and keeping it up to date. Though I must admit it helps to start developing a module, which is known to become non-trivial, from writing documentation on what it does. It becomes part of the planning and helps to “iterate” even before the code is written. Tests can serve similar purpose, when a BDD-style test framework is in use. Basically, then documentation can start with the original cases. So if anything “technical writer” can see the cases to write about from these tests, including subtle cases.

Developers are smart to optimize their work. When they see documentation pays off — they are happy to do it.

I must admit I also like to write, so I may be biased.

--

--

No responses yet