Ensure all references to technical subjects are prefaced with accessible text

[michaelmcandrew]

At many points in the user guide, we reference out of scope material that can be found in the developer guide or the administrator guide. We do this because we want the user guide to remain accessible to non technical readers. When we reference external material, we should ensure that it is done in a non intimidating way prefaced with an accessible introductory text so we do not alienate users.

Something along the lines of the following is a good starting point, to be modified as we see fit in different parts of the guide.

"X is techical and not something that users of CiviCRM are expected to carry out. Your hosting provider or system administrator should have already set this up for you. If you are having difficulties, contact them to carry out this task. They may find these chapters in the administrator guide useful: [link]".

Since this is a fairly large issue, I suggest creating seperate issues for the specific instances and referencing this task as you find them.

[seancolsen]

Agreed. Now I'm trying to figure out how we can implement this change from a practical perspective.

@michaelmcandrew do you have ideas for how to make this ticket more actionable? I like the "separate tickets" idea, but I'm still not sure what criteria should be for this ticket to be "done" and closed. So far it would seem to require a complete manual scan of the User Guide which feels too demanding.

Our Style Guide currently says

For the User Guide only: We try and limit the content to tasks that the user can perform from the front end. This means that we don't go into detailed steps about installation or system administration tasks. We do however let people know that there are system administrator tasks out there (setting up an SSL certificate, configuring CiviMail etc.) and point them in the right direction when they want to know about those tasks.

Here's my proposal for how to act on this ticket:

1. Add your suggested text to the aforementioned section of the Style Guide
2. Close this ticket
3. Keep our eyes out (just personally, not programmatically) for changes needed to bring the User Guide into compliance with this Style Guide criteria, and add new tickets as necessary.

What do you think about that @michaelmcandrew ?

[michaelmcandrew]

yeah - I think Style guide is the place for this. The other option would be to have a big sprint task label or similar that we could attach to tickets that are fairly mammouth but would be acheivable at a sprint if you split the work between 4 or 5 people, if you are into those kind of tickets that are open for a while, or you want to keep them closed. up to you.

[github-actions]

This issue has had no activity in 60 days and has been marked as stale, it will be closed in 10 days.

[dvhirst]

I anticipate incorporating the concepts discussed in this issue in my development of a CiviCRM Documentation Guide.

[homotechsual]

Hi @dvhirst just to be clear - at this stage I am not neccessarily green-lighting adding a new documentation book - the content may make more sense living in the dev guide where it is now (there would need to be a significant amount of content to justify a new core book).

[homotechsual]

Either way - I look forward to reviewing the content :-)