summaryrefslogtreecommitdiff
path: root/Documentation/contributing
diff options
context:
space:
mode:
authorChristian Walter <christian.walter@9elements.com>2020-04-23 13:17:00 +0200
committerPatrick Georgi <pgeorgi@google.com>2020-05-01 13:47:06 +0000
commite4c81bcca59e94c71f7acf48c060da827afeb15a (patch)
tree992e6b67328c4b934534052dc6d9c179942e19f8 /Documentation/contributing
parent1234925ad77aa888fb28034251b950e1bc2fd480 (diff)
downloadcoreboot-e4c81bcca59e94c71f7acf48c060da827afeb15a.tar.xz
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>
Diffstat (limited to 'Documentation/contributing')
-rw-r--r--Documentation/contributing/documentation_ideas.md173
1 files changed, 173 insertions, 0 deletions
diff --git a/Documentation/contributing/documentation_ideas.md b/Documentation/contributing/documentation_ideas.md
new file mode 100644
index 0000000000..54b3efa5bc
--- /dev/null
+++ b/Documentation/contributing/documentation_ideas.md
@@ -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
+