Mini Docs

Why

1. The absence of good documentation slows down and even blocks professionals from doing their jobs.
2. The turnover on teams can lead to losing critical information.
3. Writing docs is hard and we need some guidance to keep our knowledge safe and useful.

Who needs to document?

Everyone on your team! Everyone can benefit from reading a good documentation (even the author can forget things) so everyone should give it back by documenting critical information.

What should we document?

Everything that’s not coded! Big decisions, planning, tools, system names, portals, IPs, environments, organizational charts, client contacts, manual processes…

Where to save them?

In the cloud! You can use some a document-specific solution or leverage a shared-files or code repository. Collaboration is a key part of good documentation!

When to write a doc?

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

How to write them?

1. Create a single starting point

2. Do not duplicate information

3. Use simple files

4. Use hirerarchy

5. Break big documents into small ones

References

• Attention Span - en.wikipedia.org/wiki/Attention_span

• A profile of education journals - researchgate.net/publication/228365620

• Reading Speed Is Slower Than Previously Thought - digest.bps.org.uk/2019/06/13/

• Socratic Questioning - unl.edu/gradstudies/connections/socratic-questioning

• Writing the first draft of your science paper - elsevier.com/connect/writing-a-science-paper-some-dos-and-donts

• Paper Sizes and Formats Explained - swiftpublisher.com/useful-articles/paper-sizes-and-formats-explained

Inspired by

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