Why Documentation matters (even when it shouldn't)
Watch the session video here.
Documenting the work that has been done is often overlooked & under-prioritized. Which is a shame, since it can provide benefits long after the engineering process has moved on. More a ringmaster than a sideshow, documentation can show off amazing code & beautiful UI in ways few other efforts beat. Writing the docs is seen as unnecessary or a waste of time. This session will provide a litany of reasons to push back on leaving out documentation from delivering a feature.
After this session you should be looking at documentation as a valuable outreach tool & powerful indicator of the breadth of community involvement. Creating documentation is a whole brain activity and one that everyone in a team can participate together. Proper documentation has an outsized impact on on-boarding new developers and training the larger team on the ins-and-outs of the project.
In this talk I'll discuss:
- Why documentation is hard for people & projects
- How documentation speaks to the overall care & vision of a project
- How to make a convincing argument to add/keep/expand project time spent in documentation
- Hint: It's not just about the bus plan
- How to make documentation fun (you heard that right)
- What makes documentation good (or bad)
- How to improve documentation
More than just another deliverable, documentation is the way to preserve the rationale, to get to the why behind a piece of code. Like funnel cake - making it can be a big mess, but the results are as sweet as they are beautiful.
At the end of this talk you should (in no particular order):
- Know how easy it can be to write docs
- Be excited to write documentation for your own projects
- Recognize some of the pitfalls & antipatterns of less-than-stellar documentation
- Contribute documentation to your favorite community project as a service to your future self & others
| Attachment | Size |
|---|---|
| Why-Documentation-Matters-BADcamp-2018.pdf | 1.68 MB |