.. _write_the_docs_7_august_2013: ====================================================== Resources for writing good documentation 7 august 2013 ====================================================== .. seealso:: - http://justwriteclick.com/book/ - http://www.justwriteclick.com - http://docs.openstack.org - http://api.openstack.org - http://justwriteclick.com/2011/10/21/google-summer-of-code-doc-summit-stories/ .. contents:: :depth: 3 Email ====== :: Anne Gentle à: 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 ! Anne ==== .. seealso:: - http://www.justwriteclick.com - http://docs.openstack.org - http://api.openstack.org - http://slideshare.net/annegentle