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