Google Season of Docs/2019/Ideas
From Gentoo Wiki
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.
Ideas
Adding Ideas
First, open this link in a new tab/window. Change the title My_new_idea in the URL to the actual title (use underscores instead of spaces), load the page again, fill in all the information and save the article. Then, edit this page and include a link to it.
PMS Rationale
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.
| Contacts | Required Skills |
|---|---|
|