A community of technology community managers, leaders, and builders.

Community Documentation


#1

Our annual discussion about motivating community members to contribute and improve the training materials or other content that the community needs, and how to make it as good as we can. Common topics include identifying needs for documentation (or other media, such as video), recruiting and providing incentives to potential contributors, organizing material and making it easy to find, interactions with paid staff, and improving quality.


#2

I’d love to join this session. I have a ton of questions about knowledge management and organization for community members and I’m happy to help pull stuff together for a session if needed.


#3

Agreed. I think what I would like to get out of this session (and others too) are a summarized set of recommendations for the wider group.

One thing I would love for us to do this year is to document our notes here on the forum so we can follow up after the event with further discussions.


#4

I’ll be there :slight_smile: Let me know if you need any prep help.

Our community has had an ongoing discussion over the past half year about balancing those from a professional writing background and their high standards vs facilitating those with a large degree of technical knowledge. We now also have a certain tome that went from community-produced to O’Reilly-released and is back to community-updated again - it’s an interesting story with a few takeaways about how to manage these sorts of things.

I’m also interested in pairing automated bits with human-produced documentation, pre-release testing (for example of Installation guides), managing multiple versions of a document and working with technical material across different operating system environments.


#5

Ooh, a couple months ago I gave a talk at the Write the Docs conference about how I encourage and support volunteers who contribute to a developer documentation wiki in my community. I put the video and notes here on my blog if anyone is interested - it’s called “Strategies for fighting documentation inertia”. This is the outline of what I explain:

  1. Talk to newcomers and beginners.
    1a) Help identify useful info to write down.
    1b) Ask encouraging questions to counter anti-documentation concerns.
  2. Think of it as a marketing problem. Make the homepage enticing to click!
    2a) More marketing: build new articles that attract more visitors.
  3. Make writing more fun: show that people read it.
    3a) Make it more fun by copyediting new stuff.
    3b) Make it more fun by making it look active.
    3c) Make it more fun by thanking people.
  4. Be there to give people permission.
  5. The docs system needs docs.
  6. Leave rough edges for others to smooth out.
    6a) Write bad first drafts as motivation.

There are also 28 other videos of great talks about documentation from this conference - it was a lot of fun, and I recommend checking them out. There are notes from the talks on this blog and here.


#6

Well worth viewing Britta’s talk or reading the notes–I recognize ways in it to address problems I’ve seen getting documentation, and the talk is a good preparation for our CLS session.


#7

I’m not a fan of video but it seems widely used. I wonder if anyone has any data, anecdotal or otherwise, that might point to the benefits of using it? How many folks have found success with video here?


#8

Two more questions that are coming to mind:

How do we deal with jargon and making documentation feel welcoming rather than a barrier to entry?

How do we best support the documentation of community values alongside technical documentation? I love BetaNYC’s recent group collaboration on community values and (unverified) I believe Free Cooper Union used GitHub to invite supporters to contribute to their list of demands.

@brittag thanks for all these resources-- bookmarking everything to read on my flight to Portland!


#9

Thanks for sharing these great resources! :smile:


#10

Very valid point to the discussion. What would be awesome to get out of the session is a set of guidelines for people who are not documentation experts for how to write clear docs that are well structured.

From my experience is is worth putting the community values in a clear place that is easy to link to. For example, in Ubuntu we pointed to http://www.ubuntu.com/about/ as a simple place to document the values.


#11

Some articles I wrote may interest people looking at documentation for software communities. First, I participated in some book sprints with FLOSS Manuals, the leading organization doing documentation in general for free software projects. But there are many caveats to consider when trying a book sprint. I cover one in detail in these articles:

https://bitly.com/bundles/praxagora/4


#12

This slide show, my most recent discussion of community documentation, may also have insights for you:

Taking Documentation to the Next Level in Young Software Projects


#13

We had a great meeting today! Check out the extensive notes:


Thanks to for being the kind sponsor for this forum!