Project:Handbook
| Handbook | |
|---|---|
| Description | The Handbook project is responsible for maintaining Gentoo's official handbook. |
| Project email | handbook@gentoo.org |
| IRC channel | #gentoo-wiki (webchat) |
| Bugs | Related bugs |
| Lead(s) | none Last elected: 2022-07-18 |
| Member(s) |
|
| Subproject(s) (and inherited member(s)) |
(none) |
| Parent Project | Wiki |
| Project listing | |
The Handbook Project exists to oversee the maintenance and evolution of the Gentoo Handbook, as part of the wiki project's effort to create useful and quality documentation for Gentoo users.
The Handbook contains Gentoo's official and crucial installation instructions, since it is risky to put official installation documentation into publicly editable namespaces.
Suggestions for Handbook improvements can be left on each section's related discussion page. Among other areas of contribution, members of the Handbook project will make it a priority to respond to these critiques.
The Handbook development guide lays-out the specifics of handbook editing.
Trusted community contributors
The Handbook project, at its discretion, delegates approved community members to assist with handbook maintenance. These individuals have made positive impact and helpful contributions around the wiki at large or particularly via discussions on handbook pages. They must be approachable in the wiki's IRC channel (#gentoo-wiki (webchat)) to discuss changes from the wiki project community or developers and continue to make contributions to maintain this role.
As always when editing the Handbook, particular attention should be made to the quality of edits, which should follow the Handbook development guide and of course the Gentoo wiki guidelines. Non-trivial changes should be appropriately tested.
Due to the handbook being Gentoo's premier document, the Handbook project may remove handbook editor privilege any time. This may include accounts which reach an timeout due to inactivity.
| Name | Role | Start date | End date | Notes |
|---|---|---|---|---|
| Immolo (Immolo) | Handbook editor | 2025-11-10 | TBD | Immolo has been very involved with user support via Gentoo internal channels and external sites. Due to his function in the community, he has a keen ability to be an early alert system for broken areas of the Handbook and has been active around the wiki for years. He's well overdue for a promotion. |
| Brian Evans (Grknight) | Handbook editor | 2024-01-11 | TBD | Former dev and trusted contributor. Always makes things better. |
| needle (Needle) | Handbook editor | 2024-01-11 | TBD | Community member |
| Zen (Zen desu) | Handbook editor | 2024-01-05 | TBD | Community member |
Roadmap
Non-trivial changes to handbooks are listed at Handbook:Main Page/Changelog. Rationale and instructions for maintaining the changelog are detailed here.
Long term / recurring tasks
- Tackle and close the open handbook discussions.
- Handle 'marking' updated sections of the Handbook for translation.
- Maintain the Handbook Development guide.
Pending tasks
- Fix wireless network section wireless networking section. Is it even possible to use wpa_supplicant / iwd on in the official minimal live image?
- Wireless does work with net-setup, however SSID names are not discoverable...
- Migrate links in the Handbook to use the new {{Link}} template so that translations can work properly.
- Terminology update: Live CD, Live DVD to "live image". See bug #903551.
- Add systemd-networkd instructions for basic DHCP and static IP addressing.
- Add a section on system timer management.
- Adjust Portage binary host section here: Handbook:Parts/Working/Features#Binary_package_support
Wontfix
Fix/update the disk partitioning sections of the amd64 and x86 Handbooks. Cover:
Possible wish list
This section was copied from the handbook development guide, and some entries may no longer be relevant, if they ever were. Please remove and/or correct items as appropriate.
This was given as an example of a wish list of items from the Gentoo community:
- Full disk encryption - One of the more popular requests, but would require yet another install path and additional caveats through the already complex Preparing the disks section.
- Full desktop environments - Aligning with official Gentoo project support of each (Project:GNOME, Project:KDE, etc.). Would add significant overhead to a very limited number of hands increase the number of projects (see areas to watch above) to formally monitor. Great support exists elsewhere on the wiki
- Accelerated graphics - Helpful for systems, but can be configured post-install and is a topic unnecessary for basic Gentoo system administration.
- Support for even MOAR bootloaders - Architecture specific, therefore must be put into blocks sections... is more than one bootloader really needed?
- Power management - Helpful for systems, but can be configured post-install and is a topic unnecessary for basic Gentoo system administration.
Done
Add instructions for creating USB-based live image from Linux. See bug #902813.Added by Zen (zen_desu) here: Special:Diff/1273365/1273604.
History
After many essential and necessary years of service, the Gentoo Documentation Project (GDP) fulfilled its purpose and the wiki was created to facilitate contribution.[1][2]
As a platform, the wiki enabled every Gentoo developer (not just those in the previous 'Documentation team') and many in the community to maintain Gentoo documentation, with most of the articles produced by the former documentation team hosted in publicly editable namespaces.
In order to clarify who would continue to assume responsibility for the Gentoo Handbook, the Handbook project was created as a sub-project of the Wiki project. Moving the handbook to the Gentoo wiki allowed:
- Developers to easily update the important parts of the Gentoo handbook (instead of relying on the documentation project developers)
- The further run-down of the GuideXML format used by Gentoo (and thus optimization of infrastructure resources)
- Consolidation of all documentation on a single platform (the Gentoo Wiki) which also ensures a common interface and writing style
- Simpler links to the handbook
See also
- Handbook:Main_Page — an effort to centralize essential documentation for initial Gentoo installation and basic system administration.
- Project:Handbook/Handbook Development — provides instructions concerning Handbook development, for Gentoo handbook authors and editors
- Suggestions for Handbook improvements - how regular users can propose fixes and improvements to the handbook