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:
Christian Walter 2020-04-23 13:17:00 +02:00 committed by Patrick Georgi
parent 1234925ad7
commit e4c81bcca5
2 changed files with 174 additions and 0 deletions

View File

@ -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

View File

@ -164,6 +164,7 @@ Contents:
* [Tutorial](tutorial/index.md) * [Tutorial](tutorial/index.md)
* [Coding Style](coding_style.md) * [Coding Style](coding_style.md)
* [Project Ideas](contributing/project_ideas.md) * [Project Ideas](contributing/project_ideas.md)
* [Documentation Ideas](contributing/documentation_ideas.md)
* [Code of Conduct](community/code_of_conduct.md) * [Code of Conduct](community/code_of_conduct.md)
* [Community forums](community/forums.md) * [Community forums](community/forums.md)
* [Project services](community/services.md) * [Project services](community/services.md)