Move some content to the Administrator Guide, as needed about civicrm-user-guide HOT 7 CLOSED

Hey William. Thanks for starting this discussion (and thanks for your thoughts too @GinkgoFJG)!

Some thoughts from me...

I agree that a lot of the earlier chapters are too technical. You shouldn't have to go through the difficult and challenging concepts of data structures, installation, etc. before seeing the basic stuff like having a look at a contact screen.

But I am concerned about how easy/practical it would be for us to clearly delineate what should be in a basic guide and what should be in an advanced guide. I think that separating the guides would add a maintenance overhead and might lead to duplication of content.

Here is a twist on what you are suggesting...

The problem with the current ordering is that it only makes sense if you are looking at CiviCRM from an implementer perspective. It starts with a lot of technical stuff "First I have to install it, then I set it up and do the data import. Then I train users on how to navigate the basic contact screen, etc." OK it is chronological, but it is alienating.

If we try an organise the book from a new user perspective, a different ordering falls out, which I think gets us quite close to what William wants.

Here's a 'sketch' of what an intro to that book would look like:

"This guide is written for users of CiviCRM. It presumes that you are sitting in front of a new installation of CiviCRM and that you'd like to know your way around. We start by looking at contacts and exploring some of the basic screens and tools that are core to CiviCRM. After this we look at how to use CiviCRM's components to help with common workflows, for example how you can use CiviContribute to track financial contributions to your organisation and run fundraising campaigns, and so on. We then move on to more advanced topics that you might want to explore once you are familiar with the basics. These include things like how to customise CiviCRM screens, how to import data, how you can use extensions that enhance the functionality offered by CivICRM, etc.

"This guide only covers things that you can do via the user interface. People that want or need delve deeper into the workings of CiviCRM may want to look at our administrator guide and developer guide that [blah blah blah]."

So the general organising principle is 'Easy to Hard', not 'Start to Finish' and the ordering would change to something like:

• Basics (contact screen, searching)
• Components
• More advanced topics like configuration, importing, custom data, etc.

We can do the same within the parts for each component. Instead of starting off with Set up, we start with simple stuff like looking at / searching for contributions, and then move on to more techical stuff like setting up financial types / accounting integration.

That way, we aren't alienating anyone at the beginning, but we are giving them a nice on ramp to more technical stuff as they become more familiar with the easier stuff.

If it is organised from easy to hard, then we would be free at a later to split it into two guides - to draw a line under a certain section and say this should go in the advanced user guide - if that made sense.

PS. I think the term administrator can lead to some confusion when talking about this and we should be careful to distinguish between:

• administrator = advanced user with admin rights doing stuff via the UI
• adminsirator = sys admin that is installing, upgrading, and doing other sys admin tasks (subject of the administrator guide)

I agree that this is some content in the user guide that should be in the (system) administrator guide. But most of the sections that @wmortada pointed out should stay in the user guide and be moved towards the end. We might want to split them out into an advanced user guide at some point, but I would vote against having them in the (system) administrator guide.

from civicrm-user-guide.

I'm closing this ticket now because:

• The Sysadmin Guide is up
• I moved some pages from the User Guide to the Sysadmin Guide already.
• I think we've pretty much reached a consensus that the line between the User Guide and the Sysadmin Guide should be drawn based on what can be done from within the GUI. If there are still topics remaining in the User Guide which break this rule, then let's definitely move them to the Sysadmin Guide. But in skimming this ticket, I'm not identifying any such topics covered here.

Happy to re-open and continue discussing if other have different thoughts.

from civicrm-user-guide.

I like the idea at first glance, but then I think on how the line breaks down between user and administrator isn't always clear. I think Events are the best example, because there are so many options for events. By the time you are doing price sets and event templates, I think you are pretty close to Admin-land.

What about clearly demarcating the level of difficulty, from User, Advance, Admin? This could be a middle-road where there are Administrator Chapters and then other chapters that name the level of skill required at the beginning of each section.

How's that for some unsolicited advice from someone not contributing to the documentation?

Cheers

from civicrm-user-guide.

@ginkgomzd thanks for your comment.

I agree that there may be some grey areas, but I don't think this is a reason for not trying to make the User Guide more user friendly. I think that separating out the parts of the User Guide that are purely focussed on the initial installation and set up of CiviCRM would be a good first step.

I'm not sure how easy it would be to indicate the level of difficulty, but that could be worth considering. What do other people think?

from civicrm-user-guide.

FYI there is more discussion about this issue happening in civicrm-docs#25

from civicrm-user-guide.

@michaelmcandrew that sounds like a very sensible suggestion. My concern ultimately is just to make the User Guide more approachable for new users. Putting the easier content first sounds like a good way to do this.

from civicrm-user-guide.

Great discussion here. Before we can get started on this, we'll need to begin the Admin Guide (hence the addition of the new label). We also need to clearly define the boundary between the User Guide and the Admin Guide. This will be a bit of a project.

Other related issues:

• https://lab.civicrm.org/documentation/docs/issues/2
• https://lab.civicrm.org/documentation/docs/issues/3

from civicrm-user-guide.