Published
2009-04-08 04:44
Dave Greenberg recently posted about our upcoming book sprint saying "almost every week folks ask whether there is a CiviCRM Book they can read".
So there must be something missing from the documentation. And given that the book will be in addition to what is on the Wiki - not a replacement for it - the two questions I am asking myself are:
'What are we missing in the documentation? And how should the documentation and the book complement each other?'
Here is my initial answer:
'If the documentation is a hands on quick reference where you go to find the answer to a specific question, then the book is the tool that enables you to make effective use of the documentation. It contains all those things you to keep in mind when using (or deciding to use) CiviCRM; the advice and best practices; details of the some of the challenges you may face; the questions you need to ask yourself to get the most out of your CiviCRM installation.'
How would you answer the above questions? It would be great to hear how you see the relationship between the book and documentation.
Filed under
Comments
In terms of an example book, I find the apress drupal book 'Pro Drupal Development' to be helpful. It steps through making something using the system and then gives a reasonable amount of reference to what else there is. After that, the drupal api website takes over.
There are 2 distinct angles that can be taken though. Development and Admin/Use.
I think if there was only one book being written it would need to have the use of civicrm covered. The technical side of it is always changing which is why the wiki (like drupals docs) will contain the latest info. Some extra dev intro stuff in the book would help though. Nothing too big or in depth though.
Once there is a long-term stable version, a dev book will be good.
I think Packt publishing and apress are very good at supporting the open source sector. Also there's Pragmatic Programmers; another good publisher.
In my view CiviCRM is very intuitive.
You can use it almost without any help.
You can administer it needing only little help.
But I think what is really needed now is a development-book so more people will get comfortable costumising it and may-be even contribute.
The development-information is scattered and not well documented. For example, CiviCRM's architecture is explained in blogs in stead of a well organised technical document.
So I would go for a development book
Quote: "You can administer it needing only little help.'
Technically, yes, you can, but if you're like many, you'll end up confused by the ACLs and will inadvertently open up private information to the world.
Part of me really hopes that the book will include a full chapter on security; part of me hopes it doesn't so I can keep my best business...
Matt
Security Auditing Available
I think you have hit it, at least partially. Frequently, a book is something one reads; it flows from chapter to chapter and takes you from point A to point B. Online documentation is something one references, where you search for a point or detail and hypertext takes you this way or that way with no enforced direction. (Of course, there are pure reference books on paper, and electronic texts that are structured like paper books.) Basically I think, largely, plaintext and hypertext and different mediums which accomplish different things.
Books are never as current as online documentation, of course, and like the previous poster said, I think an admin/use book would be a good first book. Basically if might cover, from the wiki, the four sections from planning to installation to administration to using CiviCRM. However, instead of being a wiki-reprint or a list of bullet points, it would flow (as a book does) where everything is covered meaningfully and in a meaningful order. Best practices, data organization, alternative approaches, etc. would be covered as part of the process, as opposed to a link to someplace else.
It's also rather important to note that many people simply prefer one medium over the other and will find either a book or online text more comfortable and conducive for learning material. Further, paper lends itself better to extended periods of reading and more diverse environments. So I would argue that redundancy of material between formats is not a bad thing.
I use the on-line documentation in the wiki for day-to-day and field-by-field assistance. I rely on it for current installation instructions and how-to's. The on-line documentation, but the way, is excellent and improving all the time.
I like books for background information on applications. How CiviCRM get started, who were the key advocates. I also like case studies and best practices for each of the components. Seeing how someone else maximized the use of a component gets my imagination going and helps me be a better integrator and power user for my clients.
See http://www.apress.com/info/writeforus
I'd suggest using a style similar to many tech books out there. Not a reference, but a getting started guide for a tech savvy user leading from installing, configuring, securing, using, admining, to customing and extending. Each chapter should walk through doing something, except perhaps an intro one.
O'Reilley would be a good press to publish through. Apress too.
I, and my tech guy found it a bit challenging to do the install using the information in the documentation. I do believe a more in depth section on installing setting up would be good. I also think a user's manual section would be invaluable. We are going to have to train a few people on using it, and this would be very useful.
I am really excited about this project.
As a Joomla user I would definitely like to see some example uses with Joomla and Drupal of course - so a chapter on CMS integration.
That latest version with Joomla 1.5 makes adding interaction through Joomlas menu and profiles a pleasant experience. (We had an online event registration system up in a few days). Interestingly Joomla versions have been downloaded more than Drupal but Drupal has more live installs? Is this true and why? Does the answer make a chapter? (My guess would be that Joomla users are put off by the apparent complexity of CiviCRM and possible set up issues - for me setup was not an issue).
I am just about to get to grips with the acl of Joomla and Civi - some detailed info for beginners and advanced users on the nature of this relationship with each CMS would be useful.
Becasue I am a practical bod too I would love to see some example uses/scenarios where a potential Civi user says, "I wanna do X", and then chooses a scenario/example to study. My top one would be 'How to use Joomla (Drupal) and CiviCRM to make a paid membership site.
If I had time I would offer some case studies based on current experience but it is too early yet.
Good luck with the sprint...
but with that said I have sent a number of end users to the wiki and it seems to confuse them at first.
Not sure why, but that is just what I hear and see during my trainings.
Some quick thoughts.
1. Have two wiki's one all about admin and one all about using civicrm just to simplify it more
2. simplify it more.
This is the hard part and here is where the book might bring more order.
There was a new book recently called Using Drupal by O'Reilly press, and they used situation based
learning chapters.
Maybe that is how it could be on the wiki.
Yes it covers 'Topics' but with a bit more real life application examples and more images etc.
But just my thoughts, overall I think the book really is going to offer something the wiki may not have 'funded focus'. If someone could fund a group of people enough time to touch up the wiki, it's images, videos etc it would be enough.
With all that said I do appreciate the wiki, thanks to all of those working hard to keep it going.