Resources for writing good documentation 7 august 2013

See also

Email

Anne Gentle <annegentle@gmail.com>
à:   write-the-docs@googlegroups.com
date:        7 août 2013 16:50
objet:       Re: Resources for writing good documentation

On Monday, August 5, 2013 11:30:23 PM UTC-5, Eric Holscher wrote:

Hey all,

Looks like I am going to be giving a beginners presentation about writing
docs at the PDX Python user group.
I am adding a resource section that will list good places to go to look for
information about writing docs. My current list contains:

* http://producingoss.com/en/getting-started.html
* http://docs.writethedocs.org/

What are some other good documentation resources that I might be missing ?
I hope to add all of the content from this talk back into docs.writethedocs.org,
so that it will live on.

My perspective comes from being a technical writer encouraging other technical writers to contribute to open source projects.

I coordinate the OpenStack documentation through collaborative authoring, treating the docs like code with reviewed merges and bug logging, triaging, and so on. So my audience differs a bit from yours, but there are a lot of overlapping concepts.

For the audience of programmers you want to coach to write, I’d start with audience analysis and task analysis. I’ve attended a workshop Janet Swisher gave at the 2010 Google Summer of Code Doc Sprints where this approach was extremely effective.

From http://justwriteclick.com/2011/10/21/google-summer-of-code-doc-summit-stories/

  • Who is using your tool ?

  • Why do they use your tool ?

  • What kinds of things are they trying to do ?

  • What can you assume they know ?

  • What do they probably not know when they approach your tool ?

For the audience of writers you want to encourage to write for your project, I have a book with an Open Source Documentation chapter. http://justwriteclick.com/book/

It assumes a lot of pre-requisite knowledge such as audience and task analysis. I would definitely include slides about audience analysis and task analysis when coaching devs to write.

Janet Swisher does the “encourage writers to write in the open” angle too, and has a great set of presentations at http://www.slideshare.net/janetswisher/. You can take anything from my presentations at http://slideshare.net/annegentle. I can send source if you want it. Janet and I co-presented about FLOSS Manuals at a Linux conference and the thesis there was partially “find communities of writers to work on your project’s docs.” That’s a tactic as well.

Writers not only get distracted with a style guide, but also the writing/publishing/review tools. Using a third-party “referee” style guide for style questions is ideal (like Daniel Beck said). I’d coach “just put your butt in a seat and write” the tooling can be sorted out later.

Discussing tools without focusing on the content can be a huge time waster, especially with devs. :) Encourage them to get info out of their brains.

You probably know all this instinctively, so it’s great to write it down and share !