Top Documentation Practices For Your Infra Projects

Photo by Markus Winkler on Unsplash

Writing good documentation for your projects is essential to attract readers, improve your posture towards other R&D groups and set a standard for other people when documenting.

Let us think of it for a moment, won’t we engage more in reading the articles if we found them nicely formulated and styled? Won’t other R&D engineers be inspired to write in the same standard?

DO’s

✅ Ensure spacing between paragraphs and sections, as a cramped Wiki isn’t nice to look at.

✅ Add labels to your pages so they will be found and searched up next to relevant pages.

✅ Have someone review your Wiki and give you feedback.

✅ Use table of contents in your pages.

✅ Add diagrams, code snippets and screenshots.

DON’Ts

❌ Don’t write an overwhelming Wiki page, otherwise people will be discouraged from reading.

❌ Use emoticons but don’t overdo it.

Here are some of tips you can use in order to achieve this

1. Don’t jump into inventing the wheel

As much as I endorse creativity, I often like to see what other styles and examples are out there, so I may interpolate the ideas onto my own Wiki. As such, being exposed to different styles often brings new ideas.

2. Create your own Wiki templates

As you go on documenting projects, you may find it useful to have a template (or several), that you customize and style, and not create everything from blank each time. Be it with distinguished colors, banners, macros, having a convention is useful and improves your posture towards your readers.

Besides, other engineers may learn to take your template and use it as well thus, setting a standard across other groups and teams.

Below screenshot is an example of a template we use in Confluence.

3. Know the features available to you

Be it with Confluence, Gitlab Wiki, StackOverflow or any other platform, each has its set of features/macros that are available that you can explore and use.

4. Promote other articles

Be it with hyperlinks or Macros displaying labeled pages, the more exposure the more page visits.

Enjoy!