Why Documentation matters (even when it shouldn't)
nielsonm
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
https://2018.badcamp.org/session/why-documentation-matters-even-when-it-shouldnt
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
https://2018.badcamp.org/session/why-documentation-matters-even-when-it-shouldnt