Documentation at Montara sprint

During the Point Montara Lighthouse Sprint, Alain Benbassat, David Moreton, and Don Hirst worked on making the CiviCRM documentation better with a more robust but easy to follow process for producing and improving docs.

We started with the Diátaxis Framework, which has the core idea that: 

“...there are fundamentally four identifiable kinds of documentation that respond to four different needs. The four kinds are: tutorials, how-to guides, reference, and explanation.”

This is a really helpful place to start and allows us to evaluate what we’re doing from the point of view of end users, developers, and others who will be reading the documentation with different goals. We’re in conversation with Canonical and will post further updates on this.

We also started a Style Guide.  It is not a finished item, but is good enough to be useful now.  Our intent is, eventually, to revisit the whole of the docs authoring and publication workflow. We took inspiration from Canonical, Gitlab, and Google; we welcome further contributions. The core of this effort is to be accessible in what we do and write, and as much as possible to be:

• Clear, Concise, and Friendly: Aim for a professional but approachable tone.
• Community-Oriented: Use inclusive language that welcomes users of all skill levels.
• Encouraging: Guide the user - don’t talk down to them.

One of the things we noticed is that the user interface of the current docs site has room for improvement.  We also saw that some of the docs themselves are either not where we might expect them or called something that some users might not recognise. We think this can be overcome by a slight rearrangement of the site and the introduction of tagging (using an agreed framework). Some thinking is still needed around some of this, but we have a couple of clear next steps. 

1. Improve some of the docs on the current system
2. Set up a new site where some new features can be tested.

We have the ability to automatically pull content overnight from live to the new Beta site, and as we get things to a good enough state on Beta, we can push those elements (like a new footer) to live. In this way, we should be able to see improvements in the short term while we build towards a bigger step forward. 

The Google Doc where we wrote things up initially made it a lot easier to pull notes together without going through the workflow of GitLab, which we recognise as a barrier for less technical members of our community, who nevertheless wish to contribute. We’ll leave this for now as we propose a production process of:

GPT rewrites the doc -> check and edit in a Google Doc -> store in MKDocs

This approach gives easy subsequent sharing and checking before a “good enough” replacement version goes back into MKDocs. It’s important not to strive for perfect! The GPT rewrite looks pretty reasonable with the prompt that we are using, but it still needs human review, since the AI can miss things, and also the original content may have omissions and errors. So…

• Give us feedback and comments on the documentation channel on Mattermost.
• If you want to give it a go - it’s really easy and you can probably go through the whole process in about half an hour - get in touch with the docs working group via MM > Documentation.  
• Come to the next sprint and help us move things forward.