CiviCRM Community Forums (archive)

Hey there,

I think that most people involved with a CiviCRM project (e.g. the end users, the administrators, the implementors, developers, etc.) would benefit from better documentation of the project that they are currently working on.  I'm thinking of a document that explains how CiviCRM is being used, what business processes it supports, how it has been implemented, what customisations are present, what the known issues are, etc., what the roadmap is for further development is etc.

I suspect that for most projects, this information is spread around between initial requirements and specification documents, project management software, user manuals, emails, etc. (this is certainly the case for our projects).
I am definitely not suggesting that you can do without proper project management software to keep the project on track, etc. but I think that you also need something that sits outside that tool set.

For example, at the moment, we are in the process of moving our hosting and ongoing support for our projects to another supplier  Some of these projects have been ongoing for years, others are more recent. Up until now, because at 3SD, we have 'done everything' for out clients and held a lot of knowledge implicitly, we have managed without these kind of documents.  But as we start working more and more with other orgs, they are becoming more important for us.  Being able to give the hosting and ongoing support provider an up to date '3-5 pager' that outlines the current state of each project before starting the transfer would have been super useful to help them get started with supporting the new client.  What actually happened was that for our more complex clients, we have written documents that outline customisations, known issues, etc. and for the more straight forward clients, we have passed this information over in an ad-hoc manner.

Similarly, if a key person involved in the project leaves the project (e.g. example, the main client representative) then a lot of knowledge leaves with them.  Having this written down already (or having a set of guidelines that you can give to them and tell them to write it down before they go) would be awesome.  The same is true when someone joins a project.

So what I am proposing is that we put together a set of guidelines for writing CiviCRM project documentation that covers areas like the following:

* who are the key people and organisations involved with the project and what are their roles (for both the client and the service providers)
* what business processes are supported and what parts of CiviCRM (and the CMS) are being used to support these business processes?
* a brief history of the development
* an outline of the roadmap for the organisation
* what customisations have been written
* what is the current backlog of issues that need to be fixed
* are their any known issues that will not / cannot be resolved, and if so, what are the reasons?

As well as writing the initial document, you would want to have a plan in place to revise and update it every 6/12 months.

OK - now none of this (in terms of content of process) is rocket science or anything new, but I am pretty sure that:

* for the majority of CiviCRM projects out their in the world, this documentation does not exist / is thought of as a 'nice to have' / we'll get round to that at some unspecified time in the future.
* going through the process of writing this kind of documentation will bring a lot of benefits to the project,
* being able to refer to this documentation will also be super useful

A couple more thoughts since I am here...

* writing such a document might take 1-2 days of consultant time and would be a great starting point for any organisation that is starting to provide services for a new client
* if I were a client I would really want to have such a document in place

So thanks for sticking with me

I'm really interested to know what other service providers are doing in this area

What do you think about putting together some project documentation guidelines for CiviCRM projects?

I'm going to be finishing up a few of these documents over the next few days and will through together some initial guidelines / findings.

I am reading through the User and Administrator Guide now, about 1/3 of the way through. I am thinking of a more "layperson" approach as well as what is available through CiviCRM community, for a more complete capture of the CiviCRM experience. Might make the whole process less overwhelming for us non-developers, who are working with developers to implement CiviCRM for non-profits! (I will be writing Training Manuals as well, so that hopefully any future staff/volunteer can easily do the CiviCRM-related tasks we need...) Still getting my head around the whole picture of our needs and how CiviCRM can make them happen.

"Expertise" is being generous at this point! I tend to see things from the "what organization needs-how are they doing stuff now-what do they wish to do in the future-who the heck is going to have to use it in the future" frame of reference. (and I  ask the questions that seem to drive the developers nuts to have to explain in layman terms...)
 I did read about the CiviCon event and although I don't think I'm ready for it this year, I do hope to attend the meet-ups here on the East Coast. Maybe my brain will be wrapped around the whole of CiviCRM by next year's event, when my non-profit has it in place and working  (starting a Save jar for the expense now). I drop some coin in every time I visit the forum... cha-ching!