documentation: Add documentation ideas for season of docs
Let's gather some documentation ideas for the season of docs. I reused the project ideas style (thanks Patrick). Feel free to add yourself as a mentor here. Also if you have more ideas, please add them to the document. Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter <christian.walter@9elements.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/40662 Reviewed-by: Patrick Rudolph <siro@das-labor.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
This commit is contained in:
parent
1234925ad7
commit
e4c81bcca5
|
@ -0,0 +1,173 @@
|
|||
# Documentation Ideas
|
||||
|
||||
This section collects ideas to improve the coreboot documentation and
|
||||
should serve as a pool of ideas for people who want to improve the current
|
||||
documentation status of coreboot.
|
||||
|
||||
The main purpose of this document is to gather documentation ideas for technical
|
||||
writers of the seasons of docs. Nevertheless anyone who wants to help improving
|
||||
the current documentation situation can take one of the projects.
|
||||
|
||||
Each entry should outline what would be done, the benefit it brings
|
||||
to the project, the pre-requisites, both in knowledge and parts. They
|
||||
should also list people interested in supporting people who want to work
|
||||
on them.
|
||||
|
||||
## Restructure Existing Documentation
|
||||
|
||||
The goal is to improve the user experience and structure the documentation more
|
||||
logically. The current situation makes it very hard for beginners, but also for
|
||||
experienced developers to find anything in the coreboot documentation.
|
||||
|
||||
One possible approach to restructure the documentation is to split it up such
|
||||
that we divide the group of users into:
|
||||
|
||||
* (End-)users
|
||||
Most probably users which _just_ want to use coreboot as fast as possible. This
|
||||
section should include guidelines on how to build coreboot, how to flash coreboot
|
||||
and also which hardware is currently supported.
|
||||
|
||||
* Developers
|
||||
This section should more focus on the developer side-of-view. This section would
|
||||
include how to get started developing coreboot, explaining the basic concepts of
|
||||
coreboot and also give guideance on how to proceed after the first steps.
|
||||
|
||||
* Knowledge area
|
||||
This section is very tighlight coupled to the developer section and might be merged
|
||||
into it. The _Knowledge area_ can give a technical deep dive on various drivers,
|
||||
technologies, etc.
|
||||
|
||||
* Community area
|
||||
This section gives some room for the community: Youtube channels, conferences,
|
||||
meetups, forums, chat, etc.
|
||||
|
||||
A [first approach](https://review.coreboot.org/c/coreboot/+/40327) has already been made here and might be a basis for the work.
|
||||
Most of the documentation is already there, but scattered around the documentation
|
||||
folder.
|
||||
|
||||
### Requirements
|
||||
* Understanding on how a different groups of users might use the documentation area
|
||||
* Basic understanding of how coreboot works (Can be worked out _on-the-fly_)
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## Update Howto/Guides
|
||||
|
||||
An important part to involve new people in the project, either as developer or
|
||||
as enduser, are guides and how-to's. There are already some guides which need
|
||||
to be updated to work, and could also be extended to multiple platforms, like
|
||||
Fedora or Arch-Linux. Also guidance for setting up coreboot with a Windows
|
||||
environment would be helpful.
|
||||
|
||||
In addition, the vboot guidance needs an update/extensions, that the security
|
||||
features within coreboot can be used by non-technical people.
|
||||
|
||||
For developers, how to debug coreboot and various debugging techniques need
|
||||
documentation.
|
||||
|
||||
### Requirements
|
||||
* Knowledge of virtual machines, how to install different OSs and set up the
|
||||
toolchain on different operating systems
|
||||
* Knowledge of debugging tools like gdb
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## How to Support a New Board
|
||||
|
||||
coreboot benefits from running on as many platforms as possible. Therefore we
|
||||
want to encourage new developers on porting existing hardware to coreboot.
|
||||
Guidance for those new developers need to be made such that they are able to
|
||||
take the first steps supporting new mainboards, when the SoC support already
|
||||
exists. There should be a 'how-to' guide for this. Also what are common problems
|
||||
and how to solve those.
|
||||
|
||||
### Requirements
|
||||
* Knowledge of how to add support for a new mainboard in coreboot
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## Payloads
|
||||
|
||||
The current documentation of the payloads is not very effective. There should be
|
||||
more detailed documentation on the payloads that can be selected via the make
|
||||
menuconfig within coreboot. Also the use-cases should be described in more
|
||||
detail: When to use which payload? What are the benefits of using payload X over
|
||||
Y in a specific use-case ?
|
||||
|
||||
In addition it should be made clear how additional functionality e.g. extend
|
||||
LinuxBoot with more commands, can be achieved.
|
||||
|
||||
### Requirements
|
||||
* Basic knowledge of the supported payloads like SeaBIOS, TinanoCore, LinuxBoot,
|
||||
GRUB, Linux, ...
|
||||
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
|
||||
## coreboot Util Documentation
|
||||
|
||||
coreboot inherits a variaty of utilities. The current documentation only
|
||||
provides a "one-liner" as an explanation. The list of util should be updated
|
||||
with a more detailed explanation where possible. Also more "in-depths"
|
||||
explanations should be added with examples if possible.
|
||||
|
||||
### Requirements
|
||||
* coreboot utilities
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
|
||||
## CBMEM Developer Guide
|
||||
|
||||
CBMEM is the API that provides memory buffers for the use at OS runtime. It's a
|
||||
core component and thus should be documented. Dos, don'ts and pitfalls when
|
||||
using CBMEM. This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
||||
|
||||
## CBFS Developer Guide
|
||||
|
||||
CBFS is the in-flash filesystem that is used by coreboot. It's a core component
|
||||
and thus should be documented. Update the existing CBFS.txt that still shows
|
||||
version 1 of the implementation. A [first approach](https://review.coreboot.org/c/coreboot/+/33663/2)
|
||||
has been made here.
|
||||
This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
||||
|
||||
## Region API Developer Guide
|
||||
|
||||
The region API is used by coreboot when dealing with memory mapped objects that
|
||||
can be split into chunks. It's a core component and thus should be documented.
|
||||
This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
|
@ -164,6 +164,7 @@ Contents:
|
|||
* [Tutorial](tutorial/index.md)
|
||||
* [Coding Style](coding_style.md)
|
||||
* [Project Ideas](contributing/project_ideas.md)
|
||||
* [Documentation Ideas](contributing/documentation_ideas.md)
|
||||
* [Code of Conduct](community/code_of_conduct.md)
|
||||
* [Community forums](community/forums.md)
|
||||
* [Project services](community/services.md)
|
||||
|
|
Loading…
Reference in New Issue