F = T ∇ Sτ

A lot of my current projects require writing technical documentation, and it made me think quite carefully about the best practices here. I’ve found out that there are few principles which make me the most effective. Documentation as Code is the most important one. It has the advantages like: The source of documentation could be version controlled with the well-known and mature VCS like Git; New changes could be pre-approved before submitting (e.g. as pull requests); Proper VCS could give quite rich functionality (e.g. git blame to find the author of the changes and the reason for them). Text Includes is another important principle as it allows to: Re-use the documentation fragments (e.g. headers/footers); Include live code snippets (copy-pasted snippets could easily get out of sync). Rich Formatting is a must-have for the user-friendly documentation: Automatically generated ToC; Offline syntax highlight of the source code. It allows to inc