There are already many non-standard technologies in our template, ex. monorepo and NX, so why do we need documentation? In short - we need knowledge base.
It's very important thing that solves a critical problem inherent in almost every project - we haven't an easy way to share project knowledge even within the formed team.
Let's introduce part of key sorts of documentation which every team member needs to access sometimes:
- Tasks management - dashboards, rules, measures, goals, etc.
- Processes guidelines - rules of daily meets/retro/planning/grooming/etc., requirements and agreements for every process
- Communication and responsibility guidelines - simple schemes about roles and goals, problems solving ways, etc.
- List of current technologies state: our stack, pros and cons, excerpt of discussions, problems, decision motivation and criteria, etc
- Internal code style: list of non-automated (ex. with eslint) coding rules in general or in the context of particular technology
- Applications architecture
- Repository structure
- Internal documentation
- Deploy documentation
- Links and descriptions of related resources: design, styleguide, contracts, ...
- ... etc.
Yes, there are so many points, but you probably still don't understand why we need a documentation app after all? We can just create "docs" folder, put some old-school markdown in there and write whatever we need, what's the problem?
Yes, markdown is relevant solution. But it's before we tried to form criteria:
- Consistency - all pages should look like each other (same styleguide, theming and pages patterns)
- Navigation - we should be able to navigate across whole documents
- Nested clean structure - we should see all documents in our knowledge base
- DX - writing docs process should be really comfortable, or you guaranteed to lose parts of knowledge just because nobody interested to formalize their knowledge
- Scalability/customization - complex documents requires complex instruments to describe it, and we should be able to use them
- Easy to read - pages should be structured, formatted, linked with each other, extended with custom elements which improves readability, etc.
- Single source of knowledge - all docs should be in one and only one place, you always should know where you need to go for information
- ... etc.
If you use regular markdown in your project, and have read that criteria, just ask yourself - "Does our solution suits us and meet at least one of the criteria in full? Should we review something?". And, if you answered yes - see you in our next articles about documentation app creation.