Mini Docs

Best Practicies on to write really minimal documentation for your software project.

View the Project on GitHub edumco/mini-docs

Mini Docs

Why

  1. The absence of a good documentation slows down and even blocks professionals from doing their jobs.
  2. The turnover ¹ on teams can lead to loose critical informations.
  3. Writing docs is hard and we need some guide to keep our knowledge safe and usefull.

Who needs to document?

Everyone on your team! Everyone can benefit from reading a good doc (even the author can forget something) so everyone should give it back by document critical info.

What we should document?

Everything that’s not coded! Big decisions, planing, tools, system names, portals, IPs, enviroments, team organograms, client contacts, manual processes…

Where to save them?

On cloud! You can use some document specific solution or leverage a file solution or code repository. The colaboration is key part of good docs!

When to write a doc?

While you do some work! Get some notepad and keep notes during the process. It keeps the critical info at hand and helps you to select what you should document.

How to write them?

  1. You should have a single starting point - /single-starting-point

  2. You should not dupluplicate information. - /do-not-copy

  3. You should have a clear hirearchical structure of documents.

  4. You should use simple files.

  5. You should use simple text formating to publish information.

  6. You should use text hirearchy with: Title, sections, subsections and lists.

  7. You should add references to related contents.

  8. Do not let a document increase in size, make it in small pieces.

  9. You should have a sumary listing all your sources of knowledge.

  10. Make your documents accessible to your users.

Similar concepts

Short game design document - sbgames.org/sbgames2013/proceedings/artedesign/15-dt-paper_SGDD.pdf

References

Footnotes

¹ Number of employees leaving a company