Improving the CiviCRM Documentation

Weakness of The Current Documention

The main weaknesses of the current documentation is that it is not user-centered:

• The main horizontal navigation is about creating documentation, adding a new book, and the documentation source on gitlab. This is not relevant for the primary users of a documentation website.
• The first handbook that you see is about the community policies and conventions. Again, not what a regular user is looking for.
• There is no global search. You have to open a guide in order to be able to search in that guide.

Alternative 1: Improved Navigation

Alternative 1 takes the existing documentation but presents it differently.

• The main horizontal navigation points to the current guides: installation guide, user guide, sysadmin guide, and the developer guide.
• There is a global search box.
• There is a welcoming home page inviting the visitor to either browse by type of user, or by content category, or by popularity, or just search.
• The site is multilingual, with a language switch in the site header. This allows us to better integrate existing French, Spanish, and Catalan user guides. (The site can be fully translated later. This is out-of-scope for this alternative)
• It hints at the Diátaxis framework for documentation. (not implemented because it is out-of-scope for this alternative)

Try it out!

Alternative 2: Merged Guides + AI

Why have a separate user guide, installation guide, and sysadmin guide? Let's merge them into a single guide!

And why not use AI to apply the Diátaxis framework and make the instructions clearer.

Try it out!

(Translations are out-of-scope for this initiative)