├── LICENSE ├── README.md ├── docs ├── community.md ├── culture.md ├── doctypes.md ├── general.md ├── index.md ├── managing.md ├── measuring.md ├── meetings.md ├── notes.md ├── platform.md ├── presentations.md ├── process.md ├── structure.md ├── style.css ├── style.md ├── templates.md ├── tutorials.md ├── ui.md ├── understandreader.md └── writing.md └── mkdocs.yml /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | Attribution-NonCommercial-ShareAlike 3.0 Unported 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR 10 | DAMAGES RESULTING FROM ITS USE. 11 | 12 | License 13 | 14 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE 15 | COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY 16 | COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS 17 | AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 18 | 19 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE 20 | TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY 21 | BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS 22 | CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND 23 | CONDITIONS. 24 | 25 | 1. Definitions 26 | 27 | a. "Adaptation" means a work based upon the Work, or upon the Work and 28 | other pre-existing works, such as a translation, adaptation, 29 | derivative work, arrangement of music or other alterations of a 30 | literary or artistic work, or phonogram or performance and includes 31 | cinematographic adaptations or any other form in which the Work may be 32 | recast, transformed, or adapted including in any form recognizably 33 | derived from the original, except that a work that constitutes a 34 | Collection will not be considered an Adaptation for the purpose of 35 | this License. For the avoidance of doubt, where the Work is a musical 36 | work, performance or phonogram, the synchronization of the Work in 37 | timed-relation with a moving image ("synching") will be considered an 38 | Adaptation for the purpose of this License. 39 | b. "Collection" means a collection of literary or artistic works, such as 40 | encyclopedias and anthologies, or performances, phonograms or 41 | broadcasts, or other works or subject matter other than works listed 42 | in Section 1(g) below, which, by reason of the selection and 43 | arrangement of their contents, constitute intellectual creations, in 44 | which the Work is included in its entirety in unmodified form along 45 | with one or more other contributions, each constituting separate and 46 | independent works in themselves, which together are assembled into a 47 | collective whole. A work that constitutes a Collection will not be 48 | considered an Adaptation (as defined above) for the purposes of this 49 | License. 50 | c. "Distribute" means to make available to the public the original and 51 | copies of the Work or Adaptation, as appropriate, through sale or 52 | other transfer of ownership. 53 | d. "License Elements" means the following high-level license attributes 54 | as selected by Licensor and indicated in the title of this License: 55 | Attribution, Noncommercial, ShareAlike. 56 | e. "Licensor" means the individual, individuals, entity or entities that 57 | offer(s) the Work under the terms of this License. 58 | f. "Original Author" means, in the case of a literary or artistic work, 59 | the individual, individuals, entity or entities who created the Work 60 | or if no individual or entity can be identified, the publisher; and in 61 | addition (i) in the case of a performance the actors, singers, 62 | musicians, dancers, and other persons who act, sing, deliver, declaim, 63 | play in, interpret or otherwise perform literary or artistic works or 64 | expressions of folklore; (ii) in the case of a phonogram the producer 65 | being the person or legal entity who first fixes the sounds of a 66 | performance or other sounds; and, (iii) in the case of broadcasts, the 67 | organization that transmits the broadcast. 68 | g. "Work" means the literary and/or artistic work offered under the terms 69 | of this License including without limitation any production in the 70 | literary, scientific and artistic domain, whatever may be the mode or 71 | form of its expression including digital form, such as a book, 72 | pamphlet and other writing; a lecture, address, sermon or other work 73 | of the same nature; a dramatic or dramatico-musical work; a 74 | choreographic work or entertainment in dumb show; a musical 75 | composition with or without words; a cinematographic work to which are 76 | assimilated works expressed by a process analogous to cinematography; 77 | a work of drawing, painting, architecture, sculpture, engraving or 78 | lithography; a photographic work to which are assimilated works 79 | expressed by a process analogous to photography; a work of applied 80 | art; an illustration, map, plan, sketch or three-dimensional work 81 | relative to geography, topography, architecture or science; a 82 | performance; a broadcast; a phonogram; a compilation of data to the 83 | extent it is protected as a copyrightable work; or a work performed by 84 | a variety or circus performer to the extent it is not otherwise 85 | considered a literary or artistic work. 86 | h. "You" means an individual or entity exercising rights under this 87 | License who has not previously violated the terms of this License with 88 | respect to the Work, or who has received express permission from the 89 | Licensor to exercise rights under this License despite a previous 90 | violation. 91 | i. "Publicly Perform" means to perform public recitations of the Work and 92 | to communicate to the public those public recitations, by any means or 93 | process, including by wire or wireless means or public digital 94 | performances; to make available to the public Works in such a way that 95 | members of the public may access these Works from a place and at a 96 | place individually chosen by them; to perform the Work to the public 97 | by any means or process and the communication to the public of the 98 | performances of the Work, including by public digital performance; to 99 | broadcast and rebroadcast the Work by any means including signs, 100 | sounds or images. 101 | j. "Reproduce" means to make copies of the Work by any means including 102 | without limitation by sound or visual recordings and the right of 103 | fixation and reproducing fixations of the Work, including storage of a 104 | protected performance or phonogram in digital form or other electronic 105 | medium. 106 | 107 | 2. Fair Dealing Rights. Nothing in this License is intended to reduce, 108 | limit, or restrict any uses free from copyright or rights arising from 109 | limitations or exceptions that are provided for in connection with the 110 | copyright protection under copyright law or other applicable laws. 111 | 112 | 3. License Grant. Subject to the terms and conditions of this License, 113 | Licensor hereby grants You a worldwide, royalty-free, non-exclusive, 114 | perpetual (for the duration of the applicable copyright) license to 115 | exercise the rights in the Work as stated below: 116 | 117 | a. to Reproduce the Work, to incorporate the Work into one or more 118 | Collections, and to Reproduce the Work as incorporated in the 119 | Collections; 120 | b. to create and Reproduce Adaptations provided that any such Adaptation, 121 | including any translation in any medium, takes reasonable steps to 122 | clearly label, demarcate or otherwise identify that changes were made 123 | to the original Work. For example, a translation could be marked "The 124 | original work was translated from English to Spanish," or a 125 | modification could indicate "The original work has been modified."; 126 | c. to Distribute and Publicly Perform the Work including as incorporated 127 | in Collections; and, 128 | d. to Distribute and Publicly Perform Adaptations. 129 | 130 | The above rights may be exercised in all media and formats whether now 131 | known or hereafter devised. The above rights include the right to make 132 | such modifications as are technically necessary to exercise the rights in 133 | other media and formats. Subject to Section 8(f), all rights not expressly 134 | granted by Licensor are hereby reserved, including but not limited to the 135 | rights described in Section 4(e). 136 | 137 | 4. Restrictions. The license granted in Section 3 above is expressly made 138 | subject to and limited by the following restrictions: 139 | 140 | a. You may Distribute or Publicly Perform the Work only under the terms 141 | of this License. You must include a copy of, or the Uniform Resource 142 | Identifier (URI) for, this License with every copy of the Work You 143 | Distribute or Publicly Perform. You may not offer or impose any terms 144 | on the Work that restrict the terms of this License or the ability of 145 | the recipient of the Work to exercise the rights granted to that 146 | recipient under the terms of the License. You may not sublicense the 147 | Work. You must keep intact all notices that refer to this License and 148 | to the disclaimer of warranties with every copy of the Work You 149 | Distribute or Publicly Perform. When You Distribute or Publicly 150 | Perform the Work, You may not impose any effective technological 151 | measures on the Work that restrict the ability of a recipient of the 152 | Work from You to exercise the rights granted to that recipient under 153 | the terms of the License. This Section 4(a) applies to the Work as 154 | incorporated in a Collection, but this does not require the Collection 155 | apart from the Work itself to be made subject to the terms of this 156 | License. If You create a Collection, upon notice from any Licensor You 157 | must, to the extent practicable, remove from the Collection any credit 158 | as required by Section 4(d), as requested. If You create an 159 | Adaptation, upon notice from any Licensor You must, to the extent 160 | practicable, remove from the Adaptation any credit as required by 161 | Section 4(d), as requested. 162 | b. You may Distribute or Publicly Perform an Adaptation only under: (i) 163 | the terms of this License; (ii) a later version of this License with 164 | the same License Elements as this License; (iii) a Creative Commons 165 | jurisdiction license (either this or a later license version) that 166 | contains the same License Elements as this License (e.g., 167 | Attribution-NonCommercial-ShareAlike 3.0 US) ("Applicable License"). 168 | You must include a copy of, or the URI, for Applicable License with 169 | every copy of each Adaptation You Distribute or Publicly Perform. You 170 | may not offer or impose any terms on the Adaptation that restrict the 171 | terms of the Applicable License or the ability of the recipient of the 172 | Adaptation to exercise the rights granted to that recipient under the 173 | terms of the Applicable License. You must keep intact all notices that 174 | refer to the Applicable License and to the disclaimer of warranties 175 | with every copy of the Work as included in the Adaptation You 176 | Distribute or Publicly Perform. When You Distribute or Publicly 177 | Perform the Adaptation, You may not impose any effective technological 178 | measures on the Adaptation that restrict the ability of a recipient of 179 | the Adaptation from You to exercise the rights granted to that 180 | recipient under the terms of the Applicable License. This Section 4(b) 181 | applies to the Adaptation as incorporated in a Collection, but this 182 | does not require the Collection apart from the Adaptation itself to be 183 | made subject to the terms of the Applicable License. 184 | c. You may not exercise any of the rights granted to You in Section 3 185 | above in any manner that is primarily intended for or directed toward 186 | commercial advantage or private monetary compensation. The exchange of 187 | the Work for other copyrighted works by means of digital file-sharing 188 | or otherwise shall not be considered to be intended for or directed 189 | toward commercial advantage or private monetary compensation, provided 190 | there is no payment of any monetary compensation in con-nection with 191 | the exchange of copyrighted works. 192 | d. If You Distribute, or Publicly Perform the Work or any Adaptations or 193 | Collections, You must, unless a request has been made pursuant to 194 | Section 4(a), keep intact all copyright notices for the Work and 195 | provide, reasonable to the medium or means You are utilizing: (i) the 196 | name of the Original Author (or pseudonym, if applicable) if supplied, 197 | and/or if the Original Author and/or Licensor designate another party 198 | or parties (e.g., a sponsor institute, publishing entity, journal) for 199 | attribution ("Attribution Parties") in Licensor's copyright notice, 200 | terms of service or by other reasonable means, the name of such party 201 | or parties; (ii) the title of the Work if supplied; (iii) to the 202 | extent reasonably practicable, the URI, if any, that Licensor 203 | specifies to be associated with the Work, unless such URI does not 204 | refer to the copyright notice or licensing information for the Work; 205 | and, (iv) consistent with Section 3(b), in the case of an Adaptation, 206 | a credit identifying the use of the Work in the Adaptation (e.g., 207 | "French translation of the Work by Original Author," or "Screenplay 208 | based on original Work by Original Author"). The credit required by 209 | this Section 4(d) may be implemented in any reasonable manner; 210 | provided, however, that in the case of a Adaptation or Collection, at 211 | a minimum such credit will appear, if a credit for all contributing 212 | authors of the Adaptation or Collection appears, then as part of these 213 | credits and in a manner at least as prominent as the credits for the 214 | other contributing authors. For the avoidance of doubt, You may only 215 | use the credit required by this Section for the purpose of attribution 216 | in the manner set out above and, by exercising Your rights under this 217 | License, You may not implicitly or explicitly assert or imply any 218 | connection with, sponsorship or endorsement by the Original Author, 219 | Licensor and/or Attribution Parties, as appropriate, of You or Your 220 | use of the Work, without the separate, express prior written 221 | permission of the Original Author, Licensor and/or Attribution 222 | Parties. 223 | e. For the avoidance of doubt: 224 | 225 | i. Non-waivable Compulsory License Schemes. In those jurisdictions in 226 | which the right to collect royalties through any statutory or 227 | compulsory licensing scheme cannot be waived, the Licensor 228 | reserves the exclusive right to collect such royalties for any 229 | exercise by You of the rights granted under this License; 230 | ii. Waivable Compulsory License Schemes. In those jurisdictions in 231 | which the right to collect royalties through any statutory or 232 | compulsory licensing scheme can be waived, the Licensor reserves 233 | the exclusive right to collect such royalties for any exercise by 234 | You of the rights granted under this License if Your exercise of 235 | such rights is for a purpose or use which is otherwise than 236 | noncommercial as permitted under Section 4(c) and otherwise waives 237 | the right to collect royalties through any statutory or compulsory 238 | licensing scheme; and, 239 | iii. Voluntary License Schemes. The Licensor reserves the right to 240 | collect royalties, whether individually or, in the event that the 241 | Licensor is a member of a collecting society that administers 242 | voluntary licensing schemes, via that society, from any exercise 243 | by You of the rights granted under this License that is for a 244 | purpose or use which is otherwise than noncommercial as permitted 245 | under Section 4(c). 246 | f. Except as otherwise agreed in writing by the Licensor or as may be 247 | otherwise permitted by applicable law, if You Reproduce, Distribute or 248 | Publicly Perform the Work either by itself or as part of any 249 | Adaptations or Collections, You must not distort, mutilate, modify or 250 | take other derogatory action in relation to the Work which would be 251 | prejudicial to the Original Author's honor or reputation. Licensor 252 | agrees that in those jurisdictions (e.g. Japan), in which any exercise 253 | of the right granted in Section 3(b) of this License (the right to 254 | make Adaptations) would be deemed to be a distortion, mutilation, 255 | modification or other derogatory action prejudicial to the Original 256 | Author's honor and reputation, the Licensor will waive or not assert, 257 | as appropriate, this Section, to the fullest extent permitted by the 258 | applicable national law, to enable You to reasonably exercise Your 259 | right under Section 3(b) of this License (right to make Adaptations) 260 | but not otherwise. 261 | 262 | 5. Representations, Warranties and Disclaimer 263 | 264 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING AND TO THE 265 | FULLEST EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR OFFERS THE WORK AS-IS 266 | AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE 267 | WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT 268 | LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 269 | PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, 270 | ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT 271 | DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED 272 | WARRANTIES, SO THIS EXCLUSION MAY NOT APPLY TO YOU. 273 | 274 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE 275 | LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR 276 | ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES 277 | ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS 278 | BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 279 | 280 | 7. Termination 281 | 282 | a. This License and the rights granted hereunder will terminate 283 | automatically upon any breach by You of the terms of this License. 284 | Individuals or entities who have received Adaptations or Collections 285 | from You under this License, however, will not have their licenses 286 | terminated provided such individuals or entities remain in full 287 | compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will 288 | survive any termination of this License. 289 | b. Subject to the above terms and conditions, the license granted here is 290 | perpetual (for the duration of the applicable copyright in the Work). 291 | Notwithstanding the above, Licensor reserves the right to release the 292 | Work under different license terms or to stop distributing the Work at 293 | any time; provided, however that any such election will not serve to 294 | withdraw this License (or any other license that has been, or is 295 | required to be, granted under the terms of this License), and this 296 | License will continue in full force and effect unless terminated as 297 | stated above. 298 | 299 | 8. Miscellaneous 300 | 301 | a. Each time You Distribute or Publicly Perform the Work or a Collection, 302 | the Licensor offers to the recipient a license to the Work on the same 303 | terms and conditions as the license granted to You under this License. 304 | b. Each time You Distribute or Publicly Perform an Adaptation, Licensor 305 | offers to the recipient a license to the original Work on the same 306 | terms and conditions as the license granted to You under this License. 307 | c. If any provision of this License is invalid or unenforceable under 308 | applicable law, it shall not affect the validity or enforceability of 309 | the remainder of the terms of this License, and without further action 310 | by the parties to this agreement, such provision shall be reformed to 311 | the minimum extent necessary to make such provision valid and 312 | enforceable. 313 | d. No term or provision of this License shall be deemed waived and no 314 | breach consented to unless such waiver or consent shall be in writing 315 | and signed by the party to be charged with such waiver or consent. 316 | e. This License constitutes the entire agreement between the parties with 317 | respect to the Work licensed here. There are no understandings, 318 | agreements or representations with respect to the Work not specified 319 | here. Licensor shall not be bound by any additional provisions that 320 | may appear in any communication from You. This License may not be 321 | modified without the mutual written agreement of the Licensor and You. 322 | f. The rights granted under, and the subject matter referenced, in this 323 | License were drafted utilizing the terminology of the Berne Convention 324 | for the Protection of Literary and Artistic Works (as amended on 325 | September 28, 1979), the Rome Convention of 1961, the WIPO Copyright 326 | Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 327 | and the Universal Copyright Convention (as revised on July 24, 1971). 328 | These rights and subject matter take effect in the relevant 329 | jurisdiction in which the License terms are sought to be enforced 330 | according to the corresponding provisions of the implementation of 331 | those treaty provisions in the applicable national law. If the 332 | standard suite of rights granted under applicable copyright law 333 | includes additional rights not granted under this License, such 334 | additional rights are deemed to be included in the License; this 335 | License is not intended to restrict the license of any rights under 336 | applicable law. 337 | 338 | 339 | Creative Commons Notice 340 | 341 | Creative Commons is not a party to this License, and makes no warranty 342 | whatsoever in connection with the Work. Creative Commons will not be 343 | liable to You or any party on any legal theory for any damages 344 | whatsoever, including without limitation any general, special, 345 | incidental or consequential damages arising in connection to this 346 | license. Notwithstanding the foregoing two (2) sentences, if Creative 347 | Commons has expressly identified itself as the Licensor hereunder, it 348 | shall have all rights and obligations of Licensor. 349 | 350 | Except for the limited purpose of indicating to the public that the 351 | Work is licensed under the CCPL, Creative Commons does not authorize 352 | the use by either party of the trademark "Creative Commons" or any 353 | related trademark or logo of Creative Commons without the prior 354 | written consent of Creative Commons. Any permitted use will be in 355 | compliance with Creative Commons' then-current trademark usage 356 | guidelines, as may be published on its website or otherwise made 357 | available upon request from time to time. For the avoidance of doubt, 358 | this trademark restriction does not form part of this License. 359 | 360 | Creative Commons may be contacted at http://creativecommons.org/. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Hitchhikers's Guide to Documentation 2 | 3 | See this project on 4 | [readthedocs.org](http://docs-guide.readthedocs.org/en/latest/) or read 5 | [index.md file](docs/index.md). -------------------------------------------------------------------------------- /docs/community.md: -------------------------------------------------------------------------------- 1 | Community 2 | ========= 3 | 4 | This page is about how you can encourage users and developers of open source 5 | projects to improve documentation. 6 | 7 | General observations 8 | -------------------- 9 | 10 | 1. People often are afraid of modifing documentation even if they are good 11 | enough. Best developers are actually most afraid of screwing it up. 12 | 13 | 2. In open source projects, wrong documentation with typos is better than no 14 | docs, because others will quickly correct it. 15 | 16 | 3. People don't know if their writings have any sense because they don't know 17 | when their work is read. They need appreciation. Show them that people read 18 | their work. 19 | 20 | Advices 21 | ------- 22 | 23 | 1. Intentionally leave some typos in documentation to encourage people to edit 24 | wiki and give them easy wins. 25 | 26 | 2. Expert writers are usually too busy to write documentation. Don't ask them 27 | to write some doc, write a bad and wrong one and then ask them to improve 28 | it. 29 | 30 | 3. Write thanks to the volunteer writers publicly (i.e. on Twitter). 31 | 32 | 4. Give personal permission to edit doc, i.e. on IRC. 33 | 34 | 5. Copyedit wiki every few days so it looks active. 35 | 36 | 6. Encourage people to point out what is missing. This is also a proof for the 37 | writers that somebody has read their work. 38 | -------------------------------------------------------------------------------- /docs/culture.md: -------------------------------------------------------------------------------- 1 | Culture 2 | ======= 3 | 4 | This is page is about how to promote culture of creating documentation and 5 | resist the temptation to avoid doing it. 6 | 7 | Practical advices 8 | ----------------- 9 | 10 | 1. Promote "code -> test -> doc -> ship it". Friends don't allow other friends 11 | to push code without documentation in the same way they don't allow not to 12 | write tests. Documentation is also a product. 13 | 14 | 2. Make DocDays -- a "hackathon" when developers create some kind of 15 | documentation. 16 | 17 | 3. Use gamification. 18 | 19 | 4. Publicly ashame people that they don't create documentation. 20 | 21 | 5. Make a culture of reviewing documentation in the same way as you have code 22 | reviews. That way developers know their are not anonymous and finally their 23 | documentation will be seen by other developers. 24 | 25 | 6. Encourage developers to improve documentation. Advices on [Community 26 | page](community.md) may be useful. -------------------------------------------------------------------------------- /docs/doctypes.md: -------------------------------------------------------------------------------- 1 | Documentation Types 2 | =================== 3 | 4 | This page explains differences between different types of documentation. 5 | 6 | There are three basic types of documentations: 7 | 8 | - [tutorials](tutorials.md) (aka quick start or getting started) 9 | - topical guides 10 | - reference (aka API documentation) 11 | 12 | None of these three types is a substitute for any other one. They are 13 | *complementary*. 14 | 15 | Great blog post about difference between these three basic types is available 16 | [as Jacobian blog post](http://jacobian.org/writing/what-to-write/). Below, we 17 | quickly scratch the differences. 18 | 19 | Tutorials 20 | --------- 21 | 22 | Tutorials are like a front door or a shop window. They demonstrate how your 23 | project "feels". They're important from marketing point of view. 24 | 25 | A great example of tutorials are interactive sessions. See [try 26 | Ruby](http://tryruby.org/levels/1/challenges/0) as a role model. 27 | 28 | Guides 29 | ------ 30 | 31 | Guides are meat of documentation and they should: 32 | 33 | - be comprehensive, 34 | - show vast majority of possible options (but should not show *all* possible 35 | options -- that is the task for reference), 36 | - show how all concepts fit together, 37 | - answer the question "why?". 38 | 39 | References 40 | ---------- 41 | 42 | References should: 43 | 44 | - answer the question "how?". 45 | 46 | Reference is the only type of documentation that you could autogenerate from 47 | code (i.e. from docstrings), but we don't recommend it. 48 | 49 | How-tos 50 | ------- 51 | 52 | Are step-by-step guides for specific use case. Similar to tutorial, how-tos are the front door and are important from marketing site. Link to how-tos from your marketing site. 53 | 54 | Example Applications 55 | -------------------- 56 | 57 | Code can be documentation. Example applications and environment are great 58 | examples. Some developers start from such example instead of reading 59 | documentation. Example apps are also easier and faster to create. 60 | 61 | A role model of such examples is [braintree](https://github.com/braintree). 62 | 63 | Cheat sheet 64 | ----------- 65 | 66 | Cheat sheets can contain the basic information about most important concepts 67 | from your project. 68 | 69 | What is not documentation? 70 | -------------------------- 71 | 72 | - [Presentations](presentations.md) are not documentation! 73 | 74 | 75 | 76 | -------------------------------------------------------------------------------- /docs/general.md: -------------------------------------------------------------------------------- 1 | General Notes 2 | ============= 3 | 4 | 1. Bad documentation is usually social problem, not technical one. 5 | 6 | 2. Documentation is often read by managers who choose products. Writers often 7 | forget that they are writing not only for technical audience, but their 8 | documentation is also like a shop window. Now, documentation is read not 9 | only by readers who already signed in, but also by potential users. Lack of 10 | documentation is also marketing problem. 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | The Hitchhiker's Guide to Documentation! 2 | ======================================== 3 | 4 | This Guide exists to provide advices and a best-practice handbook about creating documentation. 5 | 6 | This Guide is in the early stage but is under active development. 7 | 8 | **Feel free to [give feedback, criticize or 9 | contribute](https://github.com/chrismedrela/docs-guide/issues/new)! Don't 10 | afraid to mention what is missing. Every comment is welcome!** 11 | 12 | See this project on [github](https://github.com/chrismedrela/docs-guide) or 13 | [readthedocs.org](http://docs-guide.readthedocs.org/en/latest/). 14 | 15 | The Guide is licensed under the [Creative Commons 16 | Attribution-NonCommercial-ShareAlike 3.0 Unported 17 | license](https://creativecommons.org/licenses/by-nc-sa/3.0/). 18 | 19 | How to read this Guide? 20 | ----------------------- 21 | 22 | Start from [Process](process.md) page to what are the roles of different people and what group of topics you are interested in. -------------------------------------------------------------------------------- /docs/managing.md: -------------------------------------------------------------------------------- 1 | Managing People 2 | =============== 3 | 4 | This page is about how to split the work of creating documentation between 5 | people. 6 | 7 | The most important observation is that novices are usually better at writing 8 | and editing documentation as well as writing [templates](templates.md). There are some reasons for that: 9 | 10 | 1. They are beginners and, therefore, are in the same situation as reader. They 11 | don't have to imagine what questions may a reader have -- they just have 12 | such questions. 13 | 14 | 2. New developers find different bugs than people who know the project. 15 | 16 | Therefore, you should pair writers with new developers. Documentation should be edited by only beginners. Templates also should be written by novices. 17 | 18 | Smart people are not the best writers because it's hard for them to follow "one 19 | topic per one sentence" rule since they are just... too smart. 20 | 21 | Sometimes you need experts to write documentation. But they are usually very busy. If you want to motivate them, write a bad first draft (or ask newbies to do this) and give them such draft. 22 | 23 | Testing Documentation 24 | --------------------- 25 | 26 | You need somebody who will read your documentation. Don't allow them to use any 27 | other resource like Google. If they need it, consider it as a bug in 28 | documentation. 29 | 30 | Sometimes it's better to write documentation before implementing and testing 31 | and give the docs to the users and ask them what they would do next? This is 32 | similar to "readme driven development" -- writing readme before everything 33 | else. 34 | 35 | Finding Editors 36 | --------------- 37 | 38 | If you do not have any editors, ask OReilly for help and releasing your 39 | documentation as a book. 40 | 41 | Other observations 42 | ------------------ 43 | 44 | People care more about documentation if they are accountable for it personally 45 | (bugs in documentation). -------------------------------------------------------------------------------- /docs/measuring.md: -------------------------------------------------------------------------------- 1 | Measure Documentation Quality 2 | ============================= 3 | 4 | This page is about getting feedback from documentation users and controlling documentation quality quantitatively. 5 | 6 | Building documentation is hard and you won't get it right first time round. 7 | Therefore, you need to iterate. And that means that you need to get feedback 8 | from your readers. So include analytics in your team! 9 | 10 | 1. Use quick embedded questions like "how useful was this site?" to get 11 | feedback. 12 | 13 | 2. TODO other ways to get feedback? 14 | 15 | Metrics 16 | ------- 17 | 18 | - [Net Promoter Score](http://en.wikipedia.org/wiki/Net_Promoter) 19 | - code/doc changes ratio 20 | - documentation coverage 21 | - *TTHW*, Time to Hello World (relevant only for tutorials) -------------------------------------------------------------------------------- /docs/meetings.md: -------------------------------------------------------------------------------- 1 | Meeting notes 2 | ============= 3 | 4 | What to write? 5 | -------------- 6 | 7 | - ask yourself the question who is the audience? 8 | - define, who, what, and when? 9 | - think about what is the shared need 10 | 11 | How to write 12 | ------------ 13 | 14 | - for each section, include impact to team member, use red color 15 | - engage experts in writing the notes when you are not expert 16 | - avoid chronology 17 | 18 | Other advices 19 | ------------- 20 | 21 | 1. Use collaborative tools. 22 | 23 | 2. Offer Easter Egg to combat tl;dr syndrome (i.e. chocolate for everybody who 24 | has read the note) 25 | 26 | 3. At the meeting, spend first 10 minutes to read document, then discuss; no 27 | presentation 28 | 29 | 4. Is your meeting a monologue (presentation) or a conversation? 30 | 31 | -------------------------------------------------------------------------------- /docs/notes.md: -------------------------------------------------------------------------------- 1 | Notes 2 | ===== 3 | 4 | My private notes. 5 | 6 | The audience is: 7 | 8 | - People who have some specific problem and are looking for solution. For 9 | example, a writer may write too long sentences. Solution: make cats arrive when writing. Or write via dictation. 10 | 11 | - People who are looking for some standard of process of creating 12 | documentation. For these people, we should provide a checklist for each role. 13 | 14 | The goal is to dump all knowledge from [Write the Docs 15 | conferences](http://conf.writethedocs.org/). 16 | 17 | Proposals of Changes in Topics 18 | ------------------------------ 19 | 20 | - add: Discoverability 21 | - add: documentation support & maintenance 22 | - add: Specifications 23 | - add: Audience 24 | - rename: Measuring Documentation Quality -> Feedback 25 | - split: Measure Documentation Quality -> Measure Documentation Quality & 26 | Getting Feedback -------------------------------------------------------------------------------- /docs/platform.md: -------------------------------------------------------------------------------- 1 | Platform & Tools 2 | ================ 3 | 4 | This page is about some technical solutions (platform and tools) and technical 5 | decisions that make creating documentation easier. 6 | 7 | 1. Keep your documentation as plain text. Use some markup language, like 8 | Markdown or RestructredText. 9 | 10 | 2. Check documentation into repository. 11 | 12 | 3. Ensure your documentation system is responsive, i.e. you can view 13 | documentation on a smartphone. 14 | 15 | An example of good and supereasy platform is [readthedocs](readthedocs.org). Some companies has their own platform, i.e. DocBird at Twitter. 16 | 17 | Markup language 18 | --------------- 19 | 20 | You should use Markdown or RestructuredText. The former is easier while the latter has better programming languages support and cross references. 21 | 22 | **TODO** comparision: Markdown vs RestructuredText 23 | 24 | Other ideas 25 | ----------- 26 | 27 | - Use "verbosity" option in documentation so the reader can choose the level of 28 | details described. 29 | 30 | Problems with current approach 31 | ------------------------------ 32 | 33 | - generating APIdocs 34 | - not a wiki 35 | - long way to make an edit --> you need to go through feature requests -------------------------------------------------------------------------------- /docs/presentations.md: -------------------------------------------------------------------------------- 1 | Presentations 2 | ============= 3 | 4 | This page is about making presentation at i.e. conferences. This is not about 5 | presentations for meetings. 6 | 7 | 1. Slides without presenter are useless. Therefore, do not share presentation 8 | slides, ask the audience to make their own notes. 9 | 10 | 2. Presentation is not a form of documentation. Presentation is presenter 11 | guided and heard while documentation is self guided and read. In other 12 | words, **good presentation slides are bad documentation** and vice versa. 13 | 14 | 3. Start presentation with Questions & Answers. 15 | 16 | See also 17 | -------- 18 | 19 | - http://www.agiledeveloper.com/presentations/10_commandments_of_technical_presentations.pdf 20 | -------------------------------------------------------------------------------- /docs/process.md: -------------------------------------------------------------------------------- 1 | Process 2 | ======= 3 | 4 | This page explains the process of creating documentation and different people 5 | roles. 6 | 7 | There are following steps of creating documentation (note that some of these can be executed simultaneously, that is asynchronously): 8 | 9 | 1. **An organizer** 10 | 11 | * provides [Platform & Tools](platform.md) to create documentation and 12 | overcome technical barriers, 13 | * provides [Templates](templates.md), 14 | * enforces initial [Documentation Structure](structure.md), 15 | * provides some roadmap for creating documentation (waterfall seem to work 16 | in documentation)(this approach is used in i.e. Wordpress), 17 | * promotes [Culture](culture.md) of creating documentation and 18 | * in the case of open source projects, takes care about entire 19 | [Community](community.md) and encourage it to contribute to your project. 20 | 21 | 2. **A manager** 22 | 23 | * splits work between people and takes care of [Managing 24 | People](managing.md), 25 | * at meetings creates [Meeting Notes](meetings.md). 26 | 27 | 3. **A writer** 28 | 29 | * [Understands Reader](understandreader.md) and asks who is their audience, 30 | * chooses appropriate [Documentation Type](doctypes.md) and a 31 | [Template](templates.md) 32 | * chooses a template, 33 | * [Writes Documentation](writing.md) or improves it and 34 | * writes [Tutorials](tutorials.md) or improves existing ones. 35 | 36 | 4. **An editor** edits the documentation [Style](style.md). 37 | 38 | 5. **A designer** takes care of layout, formatting, [UI](ui.md) and 39 | readability. 40 | 41 | 6. **An analytic** 42 | 43 | * tests the documentation on readers and get feedback from them, 44 | * [Measures Documentation Quality](measuring.md) and makes conclusions. 45 | 46 | 7. The next iteration happens because building documentation is hard and you 47 | won't get it right first time round. 48 | 49 | **A presenter** creates [Presentations](presentations.md), not documentation! 50 | 51 | If you are not listed in this list, please [tell us 52 | that](https://github.com/chrismedrela/docs-guide/issues/new). 53 | 54 | Note that one person can have many roles, i.e. a writer can be its own editor 55 | (however it's not recommended). -------------------------------------------------------------------------------- /docs/structure.md: -------------------------------------------------------------------------------- 1 | Documentation Structure 2 | ======================= 3 | 4 | This page is about how to split huge documentation base into pages and how to 5 | structure pages. 6 | 7 | General observations 8 | -------------------- 9 | 10 | 1. Most documentation grow organically, that is there is no structure. Somebody 11 | must enforce a structure at the beginning. 12 | 13 | 2. If writers do not know where to put their work, the structure is bad. 14 | 15 | 3. People won't read entire documentation from cover to cover. Therefore, there 16 | is no sense in structuring documentation to minimize duplication between 17 | pages. 18 | 19 | 4. People don't like *click insanity*. This should be the objective even if 20 | that results in duplicated information in a lot of pages. 21 | 22 | 5. Information is no longer a value; filtering information and giving us the 23 | right information and teaching us is now a value. Therefore, it's not enough 24 | to just give some obscure reference with no use cases. You need to take care 25 | of maintaining structure that makes the documentation easy to search. For 26 | example, there should be "search" tool or an index. In the case of 27 | single-page documentation, the reader can use searching builtin into 28 | browser. 29 | 30 | How to find good structure? 31 | --------------------------- 32 | 33 | All documentation can be split by the target audience. People know what role 34 | they are, that is if they are Designers, Organizers or Editors. That way, they 35 | can easily narrow the scope of pages they are interested in. Look at this 36 | Guide. If we just put all the pages on one list, you would have to check 15 37 | pages. But we decided to split it by audience. Since you are documentation 38 | Organizer, you have to check only six pages (and that is the worst case!). 39 | 40 | If there is too much material for one audience for one page, you should split it, possibly via topic, as in this Guide. 41 | 42 | **Practical advice**: put all topics on post-it stickers and then try to 43 | organize them. 44 | 45 | One Entry Point 46 | --------------- 47 | 48 | It's important to have one page with links to every other documentation page. A 49 | good example is [Django documentation](https://docs.djangoproject.com/en/1.8/). 50 | 51 | At the same time do not forget, that people can get to your documentation 52 | through different paths because web is just pages with hyperlinks. So they may 53 | not go through the front door. 54 | 55 | Single page documentation 56 | ------------------------- 57 | 58 | We recommend single page documentation for non-introductonary documentation. A 59 | role model is [CoffeeScript main page](http://coffeescript.org/). 60 | 61 | Don't misunderstand it. It's not about mixing tutorials, guides and API 62 | references on one page. It's about i.e. putting entire reference on one page. 63 | 64 | There are a few arguments behind single page documentation: 65 | 66 | 67 | 68 | 1. *Click insanity* -- people don't like lot's of clicking to find out 69 | interesting piece of information. 70 | 71 | 2. Searching single-page documentation is easier and faster than googling. Yes, 72 | browsers have search tool and it's free. 73 | 74 | 3. Scrolling is natural (really). 75 | 76 | 77 | 78 | There are some downsides: 79 | 80 | 81 | 82 | 1. Google will probably land you in wrong section. 83 | 84 | 2. It's bad from marketing point. People will find your single page tutorial 85 | and say "shit, it's too long". Therefore, don't use it for introductory 86 | materials like tutorials. 87 | 88 | 3. It's hard to link to sections of such documentation. Although good anchors 89 | solve the problem. 90 | 91 | 92 | 93 | When using single-page, you should provide **persistent navigation**, otherwise 94 | you risk *scroll insanity*. You can also provide *dynamic orientation*, so 95 | navigation shows where on the page you are. 96 | 97 | Page structure 98 | -------------- 99 | 100 | Inside one page, you also need some structure. Below, we listed the most common structures: 101 | 102 | - **tell a story** -- follow a linear timeline. Walkthrough. 103 | 104 | - **paint a picture** -- describe everything on the screen. Use when 105 | introducing a feature or tool 106 | 107 | - **reference** -- introduce one at a time and describe. 108 | 109 | - **theme + situations** -- idea and use cases. Use in introduction to a 110 | concept. 111 | 112 | - **drill down** -- general to specific. 113 | 114 | - **level up** -- start simple (information hiding) and reveal it as you go 115 | along. Use in Getting Started. 116 | -------------------------------------------------------------------------------- /docs/style.css: -------------------------------------------------------------------------------- 1 | span.warn { 2 | margin-left: 25px; 3 | margin-right: 25px; 4 | margin-top: -10px; 5 | width: 48px; 6 | height: 48px; 7 | float: left; 8 | display: block; 9 | background: url(http://findicons.com/icon/download/69037/alert/48/png) left top; 10 | } -------------------------------------------------------------------------------- /docs/style.md: -------------------------------------------------------------------------------- 1 | Style 2 | ===== 3 | 4 | Some language structures, tenses etc. makes docs unclear. This page is about 5 | what kind of language to use. 6 | 7 | General advices 8 | --------------- 9 | 10 | - Avoid passive voice and clearly state who is the subject. It's also hard to 11 | translate passive voice to some languages. 12 | 13 | - Use the noun (referent) instead of "it" when "it" is undefined or can be 14 | unclear. 15 | 16 | - Use specific terms instead of vague and generic ones. 17 | 18 | - Name your ideas. 19 | 20 | - Be terse. Translation costs are huge (0.25$ / word / language) 21 | 22 | - Make your sentences simple. 23 | 24 | - Use simple words. You can prepare a list of common simple English words and 25 | configure your text editor to underline all words that are not in the list. 26 | 27 | - Use [hemingwayapp.com](http://hemingwayapp.com). 28 | 29 | - Follow [RFC language guide](http://www.faqs.org/rfcs/rfc2119.html). 30 | 31 | - Read good example: 32 | 33 | + Vintage cookbooks 34 | + Martha Stewart 35 | + Dorothy Parker 36 | 37 | Simplified Technical English 38 | ---------------------------- 39 | 40 | Use [Simplified Technical English](http://en.wikipedia.org/wiki/Simplified_Technical_English) which is a carefully limited and standardized subset of English to reduce ambiguity. 41 | 42 | - Write shorter sentences. 43 | 44 | - One topic per sentence (especially important for smart people because it's 45 | harder for smart people to follow this rule). 46 | 47 | - Use valid nomenclature. No slang! 48 | 49 | - There are four basic sentence structures: 50 | 51 | + Statement, description or explanation. 52 | + Step and action (procedures) 53 | 54 | > "put switch in out" => "move the switch to the off position" 55 | 56 | + Cause and effect (fault isolation) 57 | 58 | > "test the voltage after the circuit energizes" => "energize the 59 | > circuit , then make a test of the voltage" 60 | 61 | + Call-outs, tables and headlines (illustrations). 62 | 63 | - Avoid gerunds (-ing). 64 | 65 | - Avoid nouns as verbs (i.e. "test" => "make a test"). 66 | 67 | - Avoid conditional tenses. 68 | 69 | - Use "can" to indicate a possibility. 70 | 71 | - Avoid word clusters. 72 | 73 | See also 74 | -------- 75 | 76 | * [Jacobian blog post about 77 | grammar](http://jacobian.org/writing/technical-style/#grammar) 78 | -------------------------------------------------------------------------------- /docs/templates.md: -------------------------------------------------------------------------------- 1 | Templates 2 | ========= 3 | 4 | This page is about using templates to i.e. standardize documentation. 5 | 6 | One of the worst things in writing documentation is when you start with the blank page. You have no idea, what questions you should answer and how the page should be structured. 7 | 8 | Using templates solves two problems. First, it's a tool to enforce 9 | standardization, that is each page has the same structure. This lowers the time 10 | of searching documentation. The second reason to use templates is to include 11 | there question checklist to show writers what information they should include. -------------------------------------------------------------------------------- /docs/tutorials.md: -------------------------------------------------------------------------------- 1 | Tutorials 2 | ========= 3 | 4 | Tutorials should: 5 | 6 | - give people easy wins, 7 | 8 | - be quick (a new user should experience success in less than half an hour), 9 | 10 | - demonstrate how your project "feels", 11 | 12 | - introduce high-level concepts from your project (i.e. views, models and 13 | controllers in the case of MVC web framework). 14 | 15 | It's important that the frustration is biggest at the beginning of using 16 | library because the user usually don't know even the basic concepts from your 17 | project. Therefore, it's really important to reduce friction in tutorials. 18 | 19 | Good API references are really bad tutorials (i.e. man documentation). 20 | 21 | Be step-by-step ("step one", "step two" sections in tutorials). 22 | 23 | See also 24 | -------- 25 | 26 | - [Jacobian great blog post](http://jacobian.org/writing/what-to- 27 | write/#tutorials) about differences between tutorials, guides and API 28 | references. -------------------------------------------------------------------------------- /docs/ui.md: -------------------------------------------------------------------------------- 1 | Formatting 2 | ========== 3 | 4 | 1. Use "pocos" -- huge text put on the margin for readers who only glance at 5 | the text. 6 | 7 | 2. Use colors. 8 | 9 | 3. Use icons. You can find free icons on the net. 10 | 11 | 4. Use lists instead of paragraphs. 12 | 13 | Use code snippets, diagrams, icons and so on helps to overcome the monotony of 14 | text. 15 | 16 | See also 17 | -------- 18 | 19 | - [Jacobian blog post "technical 20 | style"](http://jacobian.org/writing/technical-style/#markup) 21 | -------------------------------------------------------------------------------- /docs/understandreader.md: -------------------------------------------------------------------------------- 1 | Understand Reader 2 | ================= 3 | 4 | This page is about the first step for writer, that is asking themself some questions. 5 | 6 | Ask yourself the following questions: 7 | 8 | * Who is your audience? 9 | 10 | - Is it a single developer or a huge company? 11 | 12 | * What does the reader already know? What kind of reader's knowledge can you 13 | assume? 14 | 15 | - Does the reader know the basic concepts from your project? I.e., if 16 | you're documenting MVC web framework, can you assume that your reader 17 | knows what is a model, view and controller? 18 | 19 | - Does the reader know the language your project is written in? What is 20 | their level? 21 | 22 | * What is the goal of your reader? 23 | 24 | - Does they have some problem that he needs to solve? 25 | - Does they want to have the overview of your project or of some part of 26 | it? 27 | 28 | What to do next? 29 | ---------------- 30 | 31 | Now, you should choose a template (see [Templates](templates.md)) and then, start [Writing Documentation](writing.md). -------------------------------------------------------------------------------- /docs/writing.md: -------------------------------------------------------------------------------- 1 | Writing Documentation 2 | ===================== 3 | 4 | General advices 5 | --------------- 6 | 7 | 1. Compare bad/good; too less/enough/too much; before/after; good/better/best. 8 | 9 | 2. While the code says "how?", the documentation should explain "why?" (the 10 | reason for some decisions) 11 | 12 | 3. Assume that a reader doesn't know what he doesn't know. I.e., the reader may 13 | not know that the private key should be kept secret in order to cryptography 14 | remain secure. It's the writer responsibility to include that information. 15 | You need to be mistake-proof. By the way, see 16 | [mistakeproofing.com](http://mistakeproofing.com) for some ideas outside our 17 | industry. 18 | 19 | 4. Provide good defaults. 20 | 21 | 5. On the other hand, don't skip explaining that the reader has choice. Your 22 | defaults should be recommendations, not true defaults. Your reader must know 23 | when they have choice. 24 | 25 | 6. Describe common use cases. If the use cases are long enough, you can turn 26 | them into [howtos](doctypes.md#how-tos). 27 | 28 | 7. If you can see some product failure, ask the developer to fix it instead of 29 | documenting around them. 30 | 31 | Too long sentences 32 | ------------------ 33 | 34 | A common problem is to write too long sentences. Long sentences are bad because: 35 | 36 | - They are hard to understand. 37 | - Every piece of doc will be translated by google translator, which cannot 38 | handle complicated structures. 39 | 40 | Solutions: 41 | 42 | - Make cats arrive when you're writing. 43 | - Write via dictation. We have "eye" and "ear" brains; when you listen to, you 44 | can't remember too much information (as opposed to when you can see the 45 | text). Ear brain can remember 3 out of 5 bullet points. 46 | 47 | Use typewriter instead of computer -- you must not make mistakes. 48 | 49 | Use Empathy 50 | ----------- 51 | 52 | Empathy is an ability to mutually experience the thoughts, emotions and direct experience of others. It should not be confused with sympathy, which is the feeling of care or concern for the state of another. 53 | 54 | Here are tips to write empathicaly: 55 | 56 | - use your own API 57 | - use other APIs and their docs so you can suffer from others lack of empathy 58 | - sample code and writing instructions are most important for reference 59 | users 60 | - tell true stories ==> give use cases 61 | - reference completeness is not enough 62 | - give most attention to your API's most common endpoints and methods; 63 | provide order for them 64 | - document edge cases! 65 | - provide meaningful error messages and HTTP response codes 66 | - role example: [twillo](twilio.com) 67 | - provide "debugging errors" section 68 | 69 | What to do next? 70 | ---------------- 71 | 72 | The next thing to do after writing is editing your documentation. See "For Editors" section. -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Documentation Guide 2 | site_description: Hitchhiker's Guide to Documentation 3 | theme: readthedocs 4 | extra_css: 5 | - style.css 6 | 7 | pages: 8 | 9 | - [index.md, Home] 10 | 11 | - [general.md, For Everyone, General Notes] 12 | - [doctypes.md, For Everyone, Documentation Types] 13 | - [process.md, For Everyone, Process] 14 | 15 | - [platform.md, For Organizers, Platform & Tools] 16 | - [templates.md, For Organizers, Templates] 17 | - [structure.md, For Organizers, Documentation Structure] 18 | - [culture.md, For Organizers, Culture] 19 | - [community.md, For Organizers, Community] 20 | 21 | - [managing.md, For Managers, Managing People] 22 | - [meetings.md, For Managers, Meeting Notes] 23 | 24 | - [understandreader.md, For Writers, Understand Reader] 25 | - [writing.md, For Writers, Writing Documentation] 26 | - [tutorials.md, For Writers, Tutorials] 27 | 28 | - [style.md, For Editors, Style] 29 | 30 | - [ui.md, For Designers, UI] 31 | 32 | - [measuring.md, For Analytics, Measuring Documentation Quality] 33 | 34 | - [presentations.md, For Presenters, Presentations] 35 | 36 | - [notes.md, Miscellaneous, Notes] --------------------------------------------------------------------------------