🔸 When I wrote my Coffee Cup website in early 2019, I wrote a page named “Technical Writing” that starts with these words: “Technical Writing is the twin of Programming” and the following sentences elsewhere: “The time where documentation was written apart from development, in separated departments, producing content in word processing tools is, or tends to be, over. (…) Documentation is the twin of Development, a helping and supporting twin.”
I must admit that I didn’t know the concept, even the philosophy of “Docs as Code” at that time. My own concept of “twin” is a self made and modest version of this philosophy which has a concrete implementation:
➡️ Use the same tools and steps to produce the documentation that you use to produce code. The Documentation is thus integrated in the whole workflow, and the Technical Writer is a member of the team.
⭐ As benefits:
- The documentation phase is not postponed to the last minutes before delivering,
- The technical writer is not reduced to a “MS Word” expert with interviewing skills,
- The technical writer uses the same tools as the developers, which eases the exchanges,
- The developer often writes the first / draft version of the documentation, the technical writer being the right person to rewrite, enrich, correct, focusing on her/his content producing skills,
- The documentation is up-to-date and easy to maintain thanks to version control systems like Git that turns into a document management system.
In this perspective of cooperation, Markdown is the right syntax: a language shared by both parts to improve teamwork, apart from any styling considerations.
Of course, the technical writer always has a key role: s/he guarantees quality content, technical writing standards, quality images and diagrams, architecture and navigation, knows when and where to insert links, which admonitions are relevant, and so much more.
Thanks to everyone who developed this concept and wrote on the subject. As a technical writer, I’m grateful.
