Christian Walter has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
documentation: Add documentation ideas for season of docs
Lets gather some documentation ideas for the season of docs. I reused the project ideas style (thanks patrick). This is WIP - feel free to add new project ideas. I will complete the project description in the next days.
Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter christian.walter@9elements.com --- A Documentation/contributing/documentation_ideas.md 1 file changed, 107 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/1
diff --git a/Documentation/contributing/documentation_ideas.md b/Documentation/contributing/documentation_ideas.md new file mode 100644 index 0000000..08541d1 --- /dev/null +++ b/Documentation/contributing/documentation_ideas.md @@ -0,0 +1,107 @@ +# Project 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. + +## Refactor 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 the developers section. 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 [https://review.coreboot.org/c/coreboot/+/40327%5D(first approach) 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 + +* Toolchain Building (various distros) +* Logging/Debugging +* VBoot + +### Requirements +* One +* Two + +### Mentors +* TBD +* TBD + +## How to Board Support + +Desc + +### Requirements +* One +* Two + +### Mentors +* TBD +* TBD + +## Payloads + +* Document all known Payloads +* Propose payloads for different use-cases (OS Support, UEFI, etc.) +* How-to build payloads? + +### Requirements +* One +* Two + +### Mentors +* TBD +* TBD + + +## coerboot util documentation + +* Update util documentation + +### Requirements +* One +* Two + +### Mentors +* TBD +* TBD \ No newline at end of file
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 2:
(7 comments)
This change is ready for review.
https://review.coreboot.org/c/coreboot/+/40662/2//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/40662/2//COMMIT_MSG@9 PS2, Line 9: Lets
Let's
Ack
https://review.coreboot.org/c/coreboot/+/40662/2//COMMIT_MSG@10 PS2, Line 10: patrick
Maaybe capitalize his name? 😄
Ack
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... PS2, Line 1: Project
Documentation
Ack
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... PS2, Line 73: technique
maybe "tools" ?
Ack
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... PS2, Line 79:
Whitespace
Ack
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... PS2, Line 89: to support
to *add* support *for*
Ack
https://review.coreboot.org/c/coreboot/+/40662/2/Documentation/contributing/... PS2, Line 112:
whitespace
Ack
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#3).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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). This is WIP - feel free to add new project ideas. I will complete the project description in the next days.
Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter christian.walter@9elements.com --- A Documentation/contributing/documentation_ideas.md 1 file changed, 120 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/3
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 3:
(4 comments)
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 56: ## Update Howto/guides Trailing space.
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 97: Payloads payloads
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 98: Support support
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 99: How-to How to
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#4).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 documenet.
Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter christian.walter@9elements.com --- A Documentation/contributing/documentation_ideas.md 1 file changed, 128 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/4
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#5).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 --- A Documentation/contributing/documentation_ideas.md 1 file changed, 128 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/5
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 5:
(4 comments)
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 56: ## Update Howto/guides
Trailing space.
Ack
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 97: Payloads
payloads
Ack
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 98: Support
support
Ack
https://review.coreboot.org/c/coreboot/+/40662/3/Documentation/contributing/... PS3, Line 99: How-to
How to
Ack
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 5: Code-Review+1
(3 comments)
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 44: [https://review.coreboot.org/c/coreboot/+/40327%5D(first approach the other way: [text](url)
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 64: VBoot all lower case, compare CB:39799
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 79: Board Support "support a new board"?
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 5:
(3 comments)
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 44: [https://review.coreboot.org/c/coreboot/+/40327%5D(first approach
the other way: [text](url)
Ack
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 64: VBoot
all lower case, compare CB:39799
Ack
https://review.coreboot.org/c/coreboot/+/40662/5/Documentation/contributing/... PS5, Line 79: Board Support
"support a new board"?
Ack
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#6).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 documenet.
Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter christian.walter@9elements.com --- A Documentation/contributing/documentation_ideas.md 1 file changed, 128 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/6
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 6: Code-Review+2
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 6:
(2 comments)
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... PS6, Line 1: # Documentation Ideas needs to be referenced from exsiting .md file
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... PS6, Line 129: ## 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't and pitfalls when using CBMEM. This "in-depth" guide is clearly for developers.
### Requirements * Deep understanding of coreboot's internals
### Mentors * 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
## 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
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#7).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 documenet.
Change-Id: I72221cbd53b99cdc946109753cf72af9c865a1e5 Signed-off-by: Christian Walter christian.walter@9elements.com --- A Documentation/contributing/documentation_ideas.md M Documentation/index.md 2 files changed, 174 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/7
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 7:
(2 comments)
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... PS6, Line 1: # Documentation Ideas
needs to be referenced from exsiting . […]
Ack
https://review.coreboot.org/c/coreboot/+/40662/6/Documentation/contributing/... PS6, Line 129:
## CBMEM developer guide […]
Ack
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 7: Code-Review+1
(2 comments)
https://review.coreboot.org/c/coreboot/+/40662/7//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/40662/7//COMMIT_MSG@12 PS7, Line 12: documenet spurious e: document
https://review.coreboot.org/c/coreboot/+/40662/7/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/7/Documentation/contributing/... PS7, Line 16: Refactor "Refactor" usually refers to code. Maybe say "restructure"?
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 7:
(2 comments)
https://review.coreboot.org/c/coreboot/+/40662/7//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/40662/7//COMMIT_MSG@12 PS7, Line 12: documenet
spurious e: document
Ack
https://review.coreboot.org/c/coreboot/+/40662/7/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/7/Documentation/contributing/... PS7, Line 16: Refactor
"Refactor" usually refers to code. […]
Ack
Hello build bot (Jenkins), Patrick Georgi, Patrick Rudolph, Angel Pons,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#8).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 --- A Documentation/contributing/documentation_ideas.md M Documentation/index.md 2 files changed, 174 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/8
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8: Code-Review+2
Felix Singer has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8: Code-Review+1
(22 comments)
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 1: # Documentation Ideas I would avoid camel case for the headlines.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 3: to improve for improving
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 11: entry proposal?
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 12: They : should also list people interested in supporting people who want to work : on them. I would rephrase that. Maybe like this?
Also, a project should have at least one person acting as a mentor for supporting the person who works on it.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 16: Restructure Restructuring
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 18: structure I would write a "to" before that. Sounds better IMO.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 22: to restructure the documentation is to split it up such : that we divide the group of users into: for the restructuring is to split the documentation up into sections targeting different groups of people and users.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 27: coreboot it
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 32: of : coreboot I would remove that, since it was mentioned right before.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 37: the developers section it
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 59: s singular
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 61: setting coreboot up setting up coreboot
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 62: E e
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 64: G g
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 64: needs an update/extensions needs improvements on the usability
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 67: technique technique_s_
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 84: support adding support
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 107: Tinanocore TianoCore
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 107: b B
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 108: Grub GRUB
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 118: provide provide_s_
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 134: don't don't_s_
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8:
Patch Set 8: Code-Review+1
(22 comments)
Thanks for your comments - can we get this merged first? I would address this afterwards because the deadline is 4th of May.
Felix Singer has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8:
(1 comment)
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 84: support
adding support
let me correct myself..
on adding (or developing?) support for new mainboards, when the SoC is already supported.
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8: Code-Review+1
(21 comments)
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 1: # Documentation Ideas
I would avoid camel case for the headlines.
I would not.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 3: to improve
for improving
I guess both works.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 11: entry
proposal?
As this is a list of ideas, IMHO it can be entries.
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 16: Restructure
Restructuring
nope
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 18: structure
I would write a "to" before that. Sounds better IMO.
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 22: to restructure the documentation is to split it up such : that we divide the group of users into:
for the restructuring is to split the documentation up into sections targeting different groups of p […]
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 27: coreboot
it
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 32: of : coreboot
I would remove that, since it was mentioned right before.
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 37: the developers section
it
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 59: s
singular
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 61: setting coreboot up
setting up coreboot
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 62: E
e
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 64: needs an update/extensions
needs improvements on the usability
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 64: G
g
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 67: technique
technique_s_
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 84: support
let me correct myself.. […]
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 107: Tinanocore
TianoCore
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 107: b
B
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 108: Grub
GRUB
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 118: provide
provide_s_
Ack
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 134: don't
don't_s_
Ack
Christian Walter has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 8:
(1 comment)
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... File Documentation/contributing/documentation_ideas.md:
https://review.coreboot.org/c/coreboot/+/40662/8/Documentation/contributing/... PS8, Line 12: They : should also list people interested in supporting people who want to work : on them.
I would rephrase that. Maybe like this? […]
Ack
Hello Felix Singer, build bot (Jenkins), Patrick Georgi, Patrick Rudolph, Angel Pons,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/40662
to look at the new patch set (#9).
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 --- A Documentation/contributing/documentation_ideas.md M Documentation/index.md 2 files changed, 174 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/40662/9
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 9: Code-Review+2
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
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 --- A Documentation/contributing/documentation_ideas.md M Documentation/index.md 2 files changed, 174 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Patrick Rudolph: Looks good to me, approved
diff --git a/Documentation/contributing/documentation_ideas.md b/Documentation/contributing/documentation_ideas.md new file mode 100644 index 0000000..54b3efa --- /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 + diff --git a/Documentation/index.md b/Documentation/index.md index b636b61..a7c4869 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -164,6 +164,7 @@ * [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)
9elements QA has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/40662 )
Change subject: documentation: Add documentation ideas for season of docs ......................................................................
Patch Set 10:
Automatic boot test returned (PASS/FAIL/TOTAL): 4/0/4 Emulation targets: "QEMU x86 q35/ich9" using payload TianoCore : SUCCESS : https://lava.9esec.io/r/3046 "QEMU x86 q35/ich9" using payload SeaBIOS : SUCCESS : https://lava.9esec.io/r/3045 "QEMU x86 i440fx/piix4" using payload SeaBIOS : SUCCESS : https://lava.9esec.io/r/3044 "QEMU AArch64" using payload LinuxBoot_u-root_kexec : SUCCESS : https://lava.9esec.io/r/3043
Please note: This test is under development and might not be accurate at all!
-
9elements QA (Code Review) -
Angel Pons (Code Review)
-
Christian Walter (Code Review)
-
Felix Singer (Code Review)
-
Patrick Georgi (Code Review)
-
Patrick Rudolph (Code Review)
-
Paul Menzel (Code Review)