Documentation protocols under consideration, for collaborator review. The next step in getting the lads to blog.
1. Technical terms are bolded and either briefly defined on the first use or linked to a definition on our other project sites, wikipedia, etc.
2. To promote long term link integrity, don’t link to ephemeral sites.
3. References to external resources can include a relevant excerpt AND a link to the external resource. Links should be the name of the resource eg <link>resource name by author</link>.
4. ONE clear and concise idea per sentence, no run-on sentences
5. Clearly explain the development process including triumphs and pitfalls so that…
5.1 collaborators can understand now
5.2 future selves can understand in 3 months or 7 years
5.3 we can extract any insights that might guide us moving forward
6. Posts should have ONE coherent theme. Break multiple themes into separate stand alone posts which can then be linked to over and over. Think about posts as documentation components that can be re-purposed.
7. If you chuckle when you read your writing, then you’re likely having fun. Having fun means we’re more likely to document consistently. Though writing coherently can be a challenge, it should never feel like a drudge.