Google Season of Docs/2019/Ideas
Season of Docs is a new Google program whose purpose is to improve the quality of documentation in open source software. It is unclear whether Gentoo will participate yet. This page aims to collect the potential ideas that could be used to gauge the interest in the project.
PMS is the specification behind Gentoo's ebuild and repository format. It is rather good as a specification goes, and we manage to fix issues and update the technical part. What is lacking is a extensive rationale section covering all the decisions made in the past.
A comprehensive rationale guide would help:
- Ebuild writers who are unsure about some of the parts of the specification. Knowing the rationale behind them would let them understand the spirit of the specification better, and make decisions following that spirit rather than guessing.
- People submitting new PMS ideas, to match them better with the direction PMS is heading and to avoid unknowingly repeating rejected ideas.
- Future PMS maintainers to better direct the project, without having to rely on memory of existing project members.
- Anyone interested in historical research.
The job involves:
- Looking for the rationale. We can help some but you will have to look for all the data that is spread across Gentoo, including old mailing list posts, blog posts, and possibly talking to past developers.
- Preparing a framework to combine the rationale with the spec. We're open to ideas. This could be inlined in the spec (with some kind of switch to control its output) or separate with appropriate cross-linking.
- Integrating as much rationale as you're able to find.