Good documentation is mission critical for the success of any software project. As a project we essentially have three audiences for our documentation:
- Users
- Site Builders
- Developers
Michael McAndrew, Dave Greenberg and I had a great discussion at the NYC Code/Testing Sprint about our documentation strategy and workflow. We have a fantastic team that has done amazing work on the CiviCRM books. We also have our original, community maintained documentation wiki. What has come out of our discussions is a proposal to improve and focus each resource so that they have clear and distinct purposes.
Our two
flossmanuals.net publications: CiviCRM (the book) and CiviCRM Developer Guide will become the official documentation. We will give the book a clearer title: CiviCRM User and Administrator Guide to match CiviCRM Developer Guide. Michael will take advantage of the html export feature from flossmanuals to export the current edition of each publication and we will integrate that html into civicrm.org so that it is easier for our users to access. The documentation wiki will hold information that is new or in flux: documentation of new features, errata, hook and api. The wiki will also hold upgrade and installation instructions since these can change with releases.
We will add a documentation step to our issue workflow so that issues, especially new features, are documented in the wiki as part of their creation or modification. As appropriate to the issue, documentors will be asked to create:
- Technical developer documentation, eg api & hook documentation
- Install / upgrade / configuration documentation
- User documentation - from the perspective of a non-technical user
New documentation will be captured in the wiki and later integrated as appropriate into one of the books.
We envision expanding the book authors into a documentation team by recruiting new members from the community. If you benefit from CiviCRM this is an important way to contribute. Some members of the documentation team may focus on the book, others on new features and others on both. If you are interested, drop a comment on this post and Michael or I will get in touch. If you find yourself figuring out some CiviCRM function or feature that's not documented or not well documented - take notes in the wiki as you go along then flesh out your notes. You just contributed to an open source project!
In order to accomplish this proposal, we will begin by sorting the wiki into two stacks: covered in the books and not covered. Wiki pages for those features covered in the books may have details not yet incorporated into the books and we can flag those for the next book sprint or for book authors to work on in the meantime. We've started an
organizing page for this sorting. You can help by adding links in the outline to the wiki pages that apply to each chapter.
When all this is done we're expecting to publish the current User/Admin Guide at something like http://book.civicrm.org/section/chapter. Then when we publish a new version of the book, we can move the move the old version to http://book.civicrm.org/archive/oldversionnumber/section/chapter. That way all links from the forum, etc. should point to the latest version and if users want the older version of the docs, they know where to find it.
We'd love to have your thoughts on this proposal. Leave a comment or join the more
extended discussion on the forum.
Comments
No thoughts - just really pleased about the progress you have made (& the effort you've put in). You all deserve a warm beer
This looks to be an excelent step foreward in creating a useful workflow for documentation, and also ensuring - as much a spossible - that stuff gets at least some documentation. I'm certainly up for helping with this. I'll check out the suggeasted links and tasks, but please keep me in touch.