Mini Docs

Minimalist self-contained documentation with tag search

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

1. Attention and reading

   • Attention span

   • Reading Speed

   • Socratic Questioning

2. Minimalist documentation

   • Minimalism Beyond the Nurnberg Funnel (John M. Carroll)

   • Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process (Scott Ambler)

   • Just-in-Time Requirements Engineering (Liskin, O. et al.)

   • Impacts of Agile Requirements Documentation Debt on Software Projects: A Retrospective Study

   • A Systematic Literature Review on Quality Criteria for Agile Requirements Specifications

3. Structured documentation

   • Implementing faceted classification for software reuse (Rubén Prieto-Díaz, R.)

   • Arc42

   • C4 Model

4. Software Documentation Impact

   • 2025 Stack Overflow Survey

   • My Review of the Atlassian 2025 DevEx Report

5. Architecture Decision Records

   • Documenting Architecture Decisions (Michael Nygard)

   • Architecture Decision Record (Martin Fowler)

   • ADR Github organization

Inspired by

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