Vilnius 2019 notes: Internal docs
Notes from the dev docs conference talk at Write the Docs Vilnius 2019.
Write the Docs Vilnius 2019 saw some excellent talks. Somewhat belatedly, I'm writing up my notes. Here's the third.
Speaker: Filipe Mendes
Twitter
Slide deck
Developer documentation for internal use
Filipe discussed his experience of starting at a new company on a new (to him) product. He explained how lack of documentation slowed him down at the start, and how he developed documentation templates and processes, improving the experience for subsequent new hires.
The state of the docs:
- Project management: JIRA tickets and user stories
- Technical docs: a README
Problems for new hires:
- Where to start in the code?
- How do components work together?
- Team member availability becomes a blocking dependency - can't code without the dev with the knowledge around.
Systemic problems and their solutions:
- Lack of knowledge process -> embed creating docs into dev processes, just like testing and review.
- No process for tech planning -> create templates for planning new features.
- Lack of info about past incidents, leading to repeating the same mistakes -> introduce postmortems, provide a template for them, and ensure they are accessible.
- Lack of clarity about changes -> Don't allow PRs without descriptions.
- Individuals prefer face to face knowledge transfer -> that's fine, but ensure knowledge is also captured in a permanent format.
Benefits of internal docs:
- You're being kind to your future self.
- Gives the opportunity to learn from problems.
- Provides visibility outside the team (allowing fewer team interuptions)
- Better onboarding.
- No silos.
A word of caution:
- This type of documentation is for the team. Introduce it gradually, and only use what serves the team.