We can't find the internet
Attempting to reconnect
Something went wrong!
Hang in there while we get back on track
Engineering Documentation • Lorna Jane Mitchell • GOTO 2022
Learn effective strategies for engineering documentation, from consistency and content guidelines to collaboration tools and automation, ensuring your documentation is accurate, accessible, and enjoyable for all audiences.
- Documentation consistency is crucial, and using a format like re-structured text (e.g., Markdown) can ensure this.
- Content consistency also comes from defining what type of content it is (e.g., text files) and providing guidelines for contributors.
- Engineering can benefit from documenting their work, but it should be maintained and scaled.
- Using open-source tools and platforms (e.g., GitHub) can facilitate collaboration and documentation.
- Documentation can be automated through tools like Vail, which can help catch errors and inconsistencies.
- Documentation review should be collaborative and include steps like reviewing, testing, and approvals.
- Providing clear contributor guidelines and templates can facilitate documentation contribution.
- Adopting a documentation framework (e.g., Diataxis) can help structure and organize content.
- Continuous deployment and reviewing can facilitate documentation iteration and improvement.
- Providing feedback mechanisms (e.g., email, screenshots) can help contributors improve their documentation.
- Scanning and linting can help catch mistakes and inconsistencies in documentation.
- Adopting a content strategy (e.g., single-sourcing or re-using content) can help streamline documentation.
- Poor documentation can lead to frustration and confusion, so it’s essential to maintain and improve documentation actively.
- Documentation should be accessible and understandable to multiple audiences (e.g., developers, users).
- Using descriptive headings and formatting can help readers quickly understand the content.
- Providing a consistent and delightful user experience in documentation is crucial.
- GitHub’s pull request reviewing collaboration tools are effective for facilitating documentation review.
- Open-source documentation platforms (e.g., Divio) can provide a foundation for documentation without requiring a dedicated documentation team.