We will be holding a Book Sprint from April 23-26 to develop a new edition of Understanding CiviCRM - the free online CiviCRM book. We'll use page to collect general ideas on ways to improve the book. Chapter specific comments should be added directly to http://en.flossmanuals.net/bin/view/CiviCRM_update following
If you're attending the sprint, please edit the page directly. Otherwise, please feel free to comment and we'll incorperate your comments into the text of the page.
Ideas to improve workflow / not make the same mistakes we made last time
communicating with people in the room
Using the IRC and talking to each other during the sprint is a great idea and really necessary. There are a few sections in the current book which repeat stuff that is covered elsewhere. Whilst in some cases this makes sense, it doesn't always, and it's really good to ask people (using your mouth or using IRC) if what you are about to write has already been written somewhere else, and discuss the best place to put stuff.
Before you start reviewing a chapter, and before you start making big changes to a chapter, talk to the person that wrote it / last edited it.
Would be great to set up a demo site that we can use to pull all images from, and have someone in charge of creating those images, and making sure that the data is there to create the images from.
working with andy
Working with Andy Oram. Andy is an editor with O'reilly and gave us lots of useful feedback on the book last year. There were some co-ordination problems because Andy was working remotley. We think we can solve these by having a more formal structure for Andy's contributions. One solution could be: at a set time each day, we work out what we'd like Andy to focus / look at. Andy goes away and looks at these areas and feeds back to us the next day.
keep formatting simple
Lets keep formatting as simple as possible. As Adam says, there are complexities when it comes to exporting to different formats, and the tools we are using to create the book aren't able to handle complex formatting. It's much easier to keep everything as simple as possible, rather than slightly complex with each person presenting things in a slightly different way.
Summary of feedback on the Current Edition
- Feedback on the current edition from Andy Oram of O'Reilly Publishers (Andy provided editorial guidance during and after last year's sprint).
- (add other feedback here...)
Structural changes to the book
Improving IS CIVICRM FOR YOU? and LET'S GO!
MM: These section headings are very cryptic and the content in them needs some sorting out.
I propose that we merge them and rename them Planning your CiviCRM project with the following chapters:
- Is CiviCRM for you?
- Project management (planning, project team, Decision Making Process, Take advantage of institutional knowledge, Technical and logistical planning, Establish a budget for your project, Identify support needs, Identify support needs, One Step at a Time,
- Your requirements (constituent-centric organization, organisation processes, Define the desired set of constituent experiences, Examine organisational goals and practices, What functions must your new CRM system address? Identify repositories of data, Identify the information that you wish to collect and track, Identify the staff who will use the system)
- Modeling your data (Thinking About Your Data)
- Technical requirements (Identify the hardware/browser that will be used by office staff, hosting)
Structure of the component sections and chapters
[todo: how can we improve these to reduce repition? are there parts that we can pull out at put in a working with CiviCRM chapter, explaining basic workflows like "the searching and more actions workflow", for example?
The concepts section
MM: This is a pretty vague name for a section. And there are some parts that don't fit here, like Who is CiviCRM. We could potentially move
Getting around CiviCRM
This might be a nice place to store chapters about workflows (i.e. searching and editing). The the contact summary screen. And also about the idea of components.
Style / general improvements
User feedback suggests that it is hard to find what you are looking for in the manual.
A client of MM's said "I had a thought about the Civi guidebook - it could really use an index at the back. So, for example if you want to look up 'adding contacts to groups', you can go straight to the index and find the exact pg number rather than having to search through the whole groups chapter. I know there's a table of contents at the front, but I don't think it's detailed enough."
Maybe an index isn't feasible but we should look at how we can make things easier to navigate.
I think we should make our chapter and section headings more straight forward and more closely linked with CiviCRM concepts to help with this. For example, we could have 'Using profiles to collect and share information' rather than collect and share information, and CiviMail rather than Emailing people.
We could easily call the later sections after the module name and then give explanatory chapter names, i.e.
- Planning fundraising
- Managing your fundraising
- Reporting on your fundraising
Also, can we avoid one word questions like "CMS?" and "Constituent?"
Less kool aid drinking / marketing speak
We should do less cool aid drinking and concentrate more on getting the message across on what it can do. Marketing speak hides the point. This book isn't an advert and some of the more flowery language is unecessary or hides the point you are trying to make:
Find: "CiviCRM has a sophisticated finance and fundraising framework" Replace: "CiviCRM's CiviContribute component is made to assist with fundraising, and any aspects of CiviCRM that involve a financial element (e.g. paid events, paid membership, etc.)" . You could replace with
Find: "CiviCRM offers the entire spectrum of all the abilities of CRM to engage your constituents" Replace: nothing
Find: "It also allows you to quickly and easily create customized web pages" Replace: "You can create customised webpages"
We made a few diagrams last time that didn't find their way into the book.
Where possible, keep text as version as agnostic as possible
No pop out boxes
Last time we had some discussion about if and how we could use pop out boxes. These didn't work that will in practice (when it came to publishing the book, etc). We should remove ths CSS styling for these boxes and (they don't render well in print and are liable to get confused when others make changes to the book. Instead, we can agree on some header prefixes, like *"Note: **",* and *"Case study: **"*
We are missing a lot of introductory paragraphs, which are important to guide people through the book, and let them know what is in the chapter. Sometimes the introductory chapters give nice background to a subject which is important, but there should be a paragraph before that which outlines what is covered in the chapter and then do the content of the chapter.
For example, in communicate more, it starts "Good communication is all about knowing your constituents. An integrated, historical record of interactions with each constituent means you have detailed knowledge that you can use when you talk to them on an individual basis." But we should outline here what Civi does with communication first, and then say that it's better to do that within Civi because you have access to all that knowledge"
We don't need to be so conditional
We should accept that not all organisations will want to make use of all functionality and don't need to spell out that all info won't be of use to all orgs.
Find: "Depending on the activities and services your organization is involved with, CiviCRM can provide you with tools for donor management, memberships, event management, email and postal communications, tracking services and reporting. For advocacy, non-profit and non-governmental groups, this often adds measurable value." Replace: CiviCRM provides you with a set of tools for donor management, memberships, event management, email and postal communications and more - the kind of things non profits do on a regular basis. Taking advantage of this out of the box toolset can add great value to your org.
Invitations to get involved
It would be nice to pepper the book with hints and suggestions about how people should get involved - to re-inforce the community nature of CiviCRM and include lots of "this would make a great community contribution" type statements. These might be via case studies of how people have got involved.
New chapters / new functionality to cover
- Who this book is aimed at - what is / isn't covered. Where else you should go for help
- Context menus / 'new ...' dropdown'
- Search configurations
- Additional dupe merge options
- Home dashboard / dashlets
- Navigation menu
- Contact subtypes
- The 'search then perform action' workflow
eg: How to changes on hold email to active?
How to delete/ update null contacts from my db?
- System workflow message templates (for sending contrib receipts, event confirms, etc.)
- Multi-language sites
- Multi-site / hierarchical org configuration and use ( we might want to skip this - kurund )
- Theming system-generated email (i.e. message templates for contribution receipts, event confirmations, etc.)
- Address parsing
- Personal Campaign pages - configuration and workflow
- Price sets
- Event templates
- Waiting list management and moderated event registration workflows
- RSVP Events/Name badges (3.3)
- Best practice for sending email / avoiding spam
- Managing bounces
Creating and customizing reports (intro w/ examples)
Should also be flagged up in modules
- Features / use-cases
- Configuring CiviCase
- Using CiviCase
Customisation and development
- Using hooks to extend and modify CiviCRM (intro with examples)
- custom templates
may be bit intro to smarty??
- Public API's
REST AJAX interface
Calling API's in template using crmAPI
Chapter specific comments
*Please add chapter specific comments directly to http://en.flossmanuals.net/bin/view/CiviCRM_updatefollowing the basic convention of :*COMMENT INITIALS: text in bold italic