User and Admin Guide book review - get involved!
If you have a look back over the documentation (previously book sprint) blog tag, you'll see that over the past few months we have been making slow and steady improvements to our documentation. We've moved the books over to CiviCRM.org and clarified the relationship between the book and the wiki. It has been pretty fun so far, but there is still lots to do, one of which is a decent review of the user and admin guide...
After the last book sprint we realised that we have come to a point where, in order to be really effective at a book sprint, we need to have a solid understanding of the state of the current book before we start. In earlier sprints, this wasn't such a big deal as we could just get together and pump out the content, but now that our book is over 300 pages and pretty comprehensive (toot toot!) we need to do the prep, have the long discussions and debates, get clarity, etc. before the sprint, so that when it comes to the sprint, we can concentrate on writing quality documentation.
I'll blog a bit more about our plans for the book sprint closer to the time, but right now I wanted to draw people's attention to the book review and invite you to get involved.
We still love the Wiki, and to show our love, writing the review of the user and admin guide book review on a wiki page. Everything you need to know is on that page, but to summarise, we want to:
- Work out what parts of CiviCRM we haven't covered
- Work out where the poor quality content is
- Agree on any high level changes to the structure of the book
This is interesting stuff (well I think so anyway!) and it would be great to get your feedback and thoughts the book as it stands. Have you read the book (or parts of it) and thought that you could do better? Have you been meaning to read or review a section and not found the time? Now would be a great time for you to do that.
The bottom half of the wiki page is a list of book sections where the review is starting to take shape. As you can see we've made a decent start already with a fair number of contributions for different community members. Now it is time to ramp up the process and make sure we've covered all the sections in time for the next book sprint (early April). Please take a section, read it, and add your thoughts on that page. Ideally, you should take a section that no one has covered yet, but feel free to read a section that has already been reviewed - the more voices the better.
Once we've done a section-by-section review, we'll look at the bigger picture and see if and how we can shift stuff around, refactor it, etc. to make it more accessible and easier to understand.
So what are you waiting for? Get stuck in and/or tell your friends and colleagues to do the same!
Oh, and one last thing. I also wrote this page on http://civicrm.org/documentation as a starting point for people who want to understand where our documentation is and also those who want to help writing it - it would be good to get your thoughts on that as well.