Documentation/contributing/documentation_ideas.md

   1 # Documentation Ideas
   2
   3 This section collects ideas to improve the coreboot documentation and
   4 should serve as a pool of ideas for people who want to improve the current
   5 documentation status of coreboot.
   6
   7 The main purpose of this document is to gather documentation ideas for technical
   8 writers of the seasons of docs. Nevertheless anyone who wants to help improving
   9 the current documentation situation can take one of the projects.
  10
  11 Each entry should outline what would be done, the benefit it brings
  12 to the project, the pre-requisites, both in knowledge and parts. They
  13 should also list people interested in supporting people who want to work
  14 on them.
  15
  16 ## Restructure Existing Documentation
  17
  18 The goal is to improve the user experience and structure the documentation more
  19 logically. The current situation makes it very hard for beginners, but also for
  20 experienced developers to find anything in the coreboot documentation.
  21
  22 One possible approach to restructure the documentation is to split it up such
  23 that we divide the group of users into:
  24
  25 * (End-)users
  26 Most probably users which _just_ want to use coreboot as fast as possible. This
  27 section should include guidelines on how to build coreboot, how to flash coreboot
  28 and also which hardware is currently supported.
  29
  30 * Developers
  31 This section should more focus on the developer side-of-view. This section would
  32 include how to get started developing coreboot, explaining the basic concepts of
  33 coreboot and also give guideance on how to proceed after the first steps.
  34
  35 * Knowledge area
  36 This section is very tighlight coupled to the developer section and might be merged
  37 into it. The _Knowledge area_ can give a technical deep dive on various drivers,
  38 technologies, etc.
  39
  40 * Community area
  41 This section gives some room for the community: Youtube channels, conferences,
  42 meetups, forums, chat, etc.
  43
  44 A [first approach](https://review.coreboot.org/c/coreboot/+/40327) has already been made here and might be a basis for the work.
  45 Most of the documentation is already there, but scattered around the documentation
  46 folder.
  47
  48 ### Requirements
  49 * Understanding on how a different groups of users might use the documentation area
  50 * Basic understanding of how coreboot works (Can be worked out _on-the-fly_)
  51
  52 ### Mentors
  53 * christian.walter@9elements.com
  54 * TBD
  55
  56 ## Update Howto/Guides
  57
  58 An important part to involve new people in the project, either as developer or
  59 as enduser, are guides and how-to's. There are already some guides which need
  60 to be updated to work, and could also be extended to multiple platforms, like
  61 Fedora or Arch-Linux. Also guidance for setting up coreboot with a Windows
  62 environment would be helpful.
  63
  64 In addition, the vboot guidance needs an update/extensions, that the security
  65 features within coreboot can be used by non-technical people.
  66
  67 For developers, how to debug coreboot and various debugging techniques need
  68 documentation.
  69
  70 ### Requirements
  71 * Knowledge of virtual machines, how to install different OSs and set up the
  72   toolchain on different operating systems
  73 * Knowledge of debugging tools like gdb
  74
  75 ### Mentors
  76 * christian.walter@9elements.com
  77 * TBD
  78
  79 ## How to Support a New Board
  80
  81 coreboot benefits from running on as many platforms as possible. Therefore we
  82 want to encourage new developers on porting existing hardware to coreboot.
  83 Guidance for those new developers need to be made such that they are able to
  84 take the first steps supporting new mainboards, when the SoC support already
  85 exists. There should be a 'how-to' guide for this. Also what are common problems
  86 and how to solve those.
  87
  88 ### Requirements
  89 * Knowledge of how to add support for a new mainboard in coreboot
  90
  91 ### Mentors
  92 * christian.walter@9elements.com
  93 * TBD
  94
  95 ## Payloads
  96
  97 The current documentation of the payloads is not very effective. There should be
  98 more detailed documentation on the payloads that can be selected via the make
  99 menuconfig within coreboot. Also the use-cases should be described in more
 100 detail: When to use which payload? What are the benefits of using payload X over
 101 Y in a specific use-case ?
 102
 103 In addition it should be made clear how additional functionality e.g. extend
 104 LinuxBoot with more commands, can be achieved.
 105
 106 ### Requirements
 107 * Basic knowledge of the supported payloads like SeaBIOS, TinanoCore, LinuxBoot,
 108   GRUB, Linux, ...
 109
 110
 111 ### Mentors
 112 * christian.walter@9elements.com
 113 * TBD
 114
 115
 116 ## coreboot Util Documentation
 117
 118 coreboot inherits a variaty of utilities. The current documentation only
 119 provides a "one-liner" as an explanation. The list of util should be updated
 120 with a more detailed explanation where possible. Also more "in-depths"
 121 explanations should be added with examples if possible.
 122
 123 ### Requirements
 124 * coreboot utilities
 125
 126 ### Mentors
 127 * christian.walter@9elements.com
 128 * TBD
 129
 130
 131 ## CBMEM Developer Guide
 132
 133 CBMEM is the API that provides memory buffers for the use at OS runtime. It's a
 134 core component and thus should be documented. Dos, don'ts and pitfalls when
 135 using CBMEM. This "in-depth" guide is clearly for developers.
 136
 137 ### Requirements
 138 * Deep understanding of coreboot's internals
 139
 140 ### Mentors
 141 * TBD
 142 * TBD
 143
 144
 145 ## CBFS Developer Guide
 146
 147 CBFS is the in-flash filesystem that is used by coreboot. It's a core component
 148 and thus should be documented. Update the existing CBFS.txt that still shows
 149 version 1 of the implementation. A [first approach](https://review.coreboot.org/c/coreboot/+/33663/2)
 150 has been made here.
 151 This "in-depth" guide is clearly for developers.
 152
 153 ### Requirements
 154 * Deep understanding of coreboot's internals
 155
 156 ### Mentors
 157 * TBD
 158 * TBD
 159
 160
 161 ## Region API Developer Guide
 162
 163 The region API is used by coreboot when dealing with memory mapped objects that
 164 can be split into chunks. It's a core component and thus should be documented.
 165 This "in-depth" guide is clearly for developers.
 166
 167 ### Requirements
 168 * Deep understanding of coreboot's internals
 169
 170 ### Mentors
 171 * TBD
 172 * TBD
 173