It’s Time To Have The Talk: Writing Documentation
“The more open and collaborative you want development to be, the more crucial docs become.” – Mark Phillips
Hack Oregon strives for transparency. Not only with our data and development process, but it’s literally our mission statement. Though it’s great to give access to code, data, and resources, it’s not so great if there’s no explanation of what it is or how to use it.
We should work just as hard to create documentation as we do to be open source, whether it’s a step-by-step tutorial, overview or reference material, because documentation is a big part of transparency.
The goal of this session is to have a thoughtful conversation on Hack Oregon documentation practices and walk away with actionable steps for projects. Though the projects will be specific to Hack Oregon, the conversation will cover topics tackled by anyone interested in documentation.
This session will discuss the following:
- The importance of documentation
- Different practices
- Known documentation pitfalls and possible solutions
- Write The Docs official guides
- Mark Phillips’ Beautiful Docs
- What To Write
- Write The Docs PDX Meetup
- Tools to write docs
In keeping with good documentation practice, the description and any notes from the session will be available publicly for edits and comment on Github.
What can Hack Oregon give to the community? Just data? No! We can provide workflows, course outlines, tool implementations, design insights; all with good documentation.
Good docs help develop standards. What can Hack Oregon provide to future Hack Oregon teams? Imagine knowing all the successes and mistakes of past teams. We shouldn’t be making the same mistake twice!
If we have great docs anyone could easily answer:
- Where are all the Hack Oregon projects?
- What were the projects?
- What problems did we tackle in those projects?
- How did we solve those problems?
- How can I piggyback off past work?
- What workflows are best for my project?
- What environment is best for my project? VirtualBox + Vagrant w/ Ubuntu OS? Python VirtualENV? Docker?
What’s your name? Do you have a role at Hack Oregon? What experience do you have writing docs? On a scale of one to ten, ten being the highest, how much do you enjoy writing documentation?
|Megan||Hack Oregon||Program Director|
Why write documentation?
- Know why of code was written and how it works
- Make onboarding at Hack Oregon easier
- Solving problems when the owner is no longer around
- See Hack Oregon's growth over time
- Inform those outside Hack Oregon how we run. What if someone from Washington wanted to start "Hack Washington"?
How can non-coders contribute?
- Explain context around the project
- In-depth note taking
- Document and catalogue subject matter
Who are we writing docs for?
- Consumers of data: public using our endpoints
- Public officials giving us data
- Future Hack Oregonians
- A resource for those who want to volunteer to easily find projects that fit their skill set and free time.
What should we document?
- Project summaries
- API methods/endpoints
- Hack University class material
- Civic Lab talks & discussion
- Could we make an ebook?
- Hack Oregon project roles
- Project timelines (task & skill level)
- Meta: How does Hack Oregon solve problems?
- How does Hack Oregon work as a organization?
- How do we get volunteers?
What have we already documented?
What are good examples of documentation you’ve seen?
What are good documentation tools?
Hack Oregon Workflows
- A Hack Oregon editor in chief with deputy editors in each team
Is it possible to write documentation templates to get people started?
- Yes. In github repos.
Where does documentation go?
- During development: with your code in your repo?
- When you’re ready to publish: as a public site alongside your published product?
How do you incentives people to write documentation?
- Say thanks! A lot!
- Find people
- Meet them half way. A doc template with smaller tasks where all they have to do is fill in the blank.