Documentation📄 and authoring🖊️ are two very diverging employments of writing and painting skills with opposed values of formalism, creativity, envisaging, and styles. Their principled distinction is driven vs drives:
-
Documentation is on-demand/request derivative of a product, must follow templates and shall be (auto-)generated and reused as much as possible.📖
📖 A strict User manual of hazardous tools is an exemplary story. -
Authoring is initiative, must take a bird's view of the subject, inspire and explain sophisticated and regulated ideas in an abstractive, friendly, and sometimes informal/playful, manner.
Documentation assumes defined, if not available, subjects (as software applications), while autoring may begin with a bare idea. (Many of the renowned works, such as concepts of relational DBs or REST, were based on "paper" concepts with little or no implementation.)
When it's a reader's headache to find and study the right documentation, with authoring, it's a burden of "pensters" to attract readers. In documenting sticking to the narrowed vocabulary and cliches is a benefactor, in authoring the repetition is a failure.
Regardless of missions, any tech writing is an expensive and exhausting exercise and, if not a hobby or bondage, must:
- have a live eager auditorium,
- excel other ways of teaching (consider quickly sketched presentation, captured video tutorial, watercooler talks),
- be long-term (updated and evolved).
The writings and collections here are ...
- The subject of personal taste, inclination, vision, and fallacies. It's up to you whether to like them or recoil in distaste.
- The subject of endless editing and rework.
- Some opuses may be in the badly readable state of 🚧draft🐝 (now skip them).
___________
🔚 You are welcome to contribute and correct errata.