A Discussion on Writing Documentation

Hack Oregon strives for transparency. Not only with data and development process, but it’s literally in the 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 more open and collaborative you want development to be, the more crucial docs become.” – Mark Phillips

I recently led a session for Hack Oregon’s Civic Lab to have a thoughtful conversation on documentation practices and, hopefully, walk away with actionable steps for Hack Oregon projects. Keeping with the practice of open source, I wanted to share what we learned from the session.

Discussion Outline

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? 

Discussion Questions

Why write documentation?

  • Know why the code was written and how it works
  • Make onboarding at Hack Oregon easier
  • Solve problems when the owner is no longer involved
  • 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 halfway. Provide  doc template with smaller tasks where all they have to do is fill in the blank.

Related Reading

In keeping with good documentation practice, the description and any notes from the session will be available publicly for edits and comment on Github.