i find that the divio/diataxis 2x2 can be -too- complete, which is harmful for earlier stage, less mature open source projects, and also equal weights areas that nobody equal weights in real life.
my system takes inspiration from real docs and creates a progression based on project maturity, aka prioritizing just the important stuff at the early stages.
- *Level 0: Basic proof of concept*
- _Example audience: you/colleagues/hobbyists_
- One sentence description for github headline
- README with API docs - goal is to save yourself from looking at source code
- *Level 1: v0.x*
- _Example audience: greenfield early adopters. Ok with missing documentation, they are here for the idea. can contribute code/docs_
- One paragraph description with more context - could be a sales pitch but also give an idea of when to use you
- Feature list/Project Goals
- Install + Config Instructions
- *Level 2: v1*
- _Example audience: brownfield early adopters. Ok with bugs, they have some problem that isnt well addressed. Needs convincing._
- Comparison vs comparable libraries
- Problem Statement - what you solve, how the developer/end user is better off with your thing than handwritten. aka Why You Exist
- Basic Examples
- Live Demos
- *Level 3: vX*
- _Example audience: early majority user. Wants ease of use, quick wins. Need to be very reliable. Needs content to sell solution to team_
- Project Status badges
- Tutorial
- Third Party Plugins/Libraries
- How-To Guide/Cookbook/Recipes
- User/Maintainer Content
- Official Blog/Project and Meeting Notes
- Talks
- 3rd Party Blogs
- Video Tutorials
- Podcasts
- Comprehensive Examples
- *Level 4: Production use for multiple years*
- _Example audience: expert user. Needs API stability/migration instructions, deep insight on how the project works and how it can solve problems. Needs to customize/adapt for at-scale/weird usecases_
- Growing the MetaLanguage
- Origin Story/Naming
- Who Uses Us
- Logos
- Quotes/endorsements/testimonials
- Link to production use
- Funding
- Migration docs from previous versions
- Roadmap
- Reader-friendly Changelog
- Anti-Docs
- Helping Contributors
- _Example audience: Industry beginner. They may not know any alternatives. You are the entire world to them._
- Explain acronyms, jargon
- "1 to N" Docs
- Different docs for different audiences (eg JS/Android/iOS)
- Different languages
- Examples
- [Vue](https://vuejs.org/)
- [Django](https://docs.djangoproject.com/en/3.0/) - some [meta thoughts here](https://jacobian.org/2009/nov/10/what-to-write/)
- [React](https://reactjs.org)
i find that the divio/diataxis 2x2 can be -too- complete, which is harmful for earlier stage, less mature open source projects, and also equal weights areas that nobody equal weights in real life.
my system takes inspiration from real docs and creates a progression based on project maturity, aka prioritizing just the important stuff at the early stages.
- *Level 0: Basic proof of concept*
- *Level 1: v0.x* - *Level 2: v1* - *Level 3: vX* - *Level 4: Production use for multiple years*