The good, the bad, the documentation: how to craft effective documentation: DrupalCon Portland 2022
Speaker: Jennifer Dust
How many times have you picked up a project and not been able to understand what is going on or why something was set a specific way; for me it's been more times than I care to count. Documentation can seem like an overwhelming task when working on a project, either there isn’t enough time allocated to accurately write some or what is there doesn’t actually make sense. I’ve spent lots of time as a developer trying to figure out how much documentation is enough and how to effectively communicate something that will be understood months or years from now.
The objective of this workshop is to engage and empower those attending with the skills to craft better documentation for themselves and for development communities. Figuring out how to start can feel like a daunting task, within this session we will do a hands-on review with a few examples of documentation and identify the areas it lacks with regards to communication, clarity, and thoroughness. Then we will walk through outlining documentation needs and how to implement them in thoughtful and straightforward ways. Documentation itself is a tool we should feel comfortable creating & using; it’s my goal that at the end of this workshop people will be encouraged to start improving their own documentation and contributing within the open source community as a whole.
How many times have you picked up a project and not been able to understand what is going on or why something was set a specific way; for me it's been more times than I care to count. Documentation can seem like an overwhelming task when working on a project, either there isn’t enough time allocated to accurately write some or what is there doesn’t actually make sense. I’ve spent lots of time as a developer trying to figure out how much documentation is enough and how to effectively communicate something that will be understood months or years from now.
The objective of this workshop is to engage and empower those attending with the skills to craft better documentation for themselves and for development communities. Figuring out how to start can feel like a daunting task, within this session we will do a hands-on review with a few examples of documentation and identify the areas it lacks with regards to communication, clarity, and thoroughness. Then we will walk through outlining documentation needs and how to implement them in thoughtful and straightforward ways. Documentation itself is a tool we should feel comfortable creating & using; it’s my goal that at the end of this workshop people will be encouraged to start improving their own documentation and contributing within the open source community as a whole.