Wagtail: Engineering transformation through documentation
Tags: wagtail, documentation, opensource, writing
Published: 2023-04-13 12:35:59

Writing is the only way to talk without being interrupted, and sometimes authors just talk on!

## Signposting the problems
In reading through the GSOD page I noticed this

![About Wagtail Docs](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s1ka2og1jnj1m5oy6lq0.png)

Here is the problem:

>There is a regular scheduled release cycle for the product (Wagtail) but not for the documentation of the product.

In essence **documentation lags behind product**

### Why is this a problem?
Whilst, this isn't common or applies only to Wagtail, most open source and even closed-source project encounter such problem of *doc lagging behind product* hence leading to doc playing catchup. GSOD strives to eliminate this.

Why this is a problem is because, *doc playing catchup to product* is a symptom of a larger systemic problem.
It may imply, that by this time next year, we might still be re-enacting this same catch-up script.

As software engineers, we know how quickly documentation goes out of date, but we also know how quickly code goes out of date - amongst many things we call it *Technical Debt*

Having given a talk on [Technical Debt in 2019](https://docs.google.com/presentation/d/1jxtaci8H7BRqwUly6un-EY9Xb97HOjIf/edit?usp=sharing&ouid=112194834423799235525&rtpof=true&sd=true) I can call the above problem - Documentation Debt.

>Wagtail (as most software projects) has some documentation debt it has to pay. But more importantly, it needs to stop accumulating compound interest on.

It is important to prioritize stopping the accumulation of interest over paying it. But it is best to do both - and both can be done.

The methodology to be applied speaks to the heart of the message - *engineering transformation through documentation*

The final output of this transformation (and this is a big and bold claim) would not be the need to gather friction logs, but to completely eliminate the need for friction logging.

This does not despise or diminish the need for Friction Logs, they are still useful in other context, but no longer for this.


### Timelines
6 months would allow us to begin to see short-term  progress, but 2-3 years is more like it.
* Initial 2-3 weeks: Learning - where and how the docs happen, who and what impacts it and when.
* 2-3 months: Unlearning - identify the problems in our star and how it occurs
* 2-3 years: Relearning - first in building systems and structures, then in building people and communities.

A more detailed timeline is to be built with mentors according to the scope to be covered.

#### What to expect
By the next [release schedule in August](https://github.com/wagtail/wagtail/wiki/Release-schedule) the documentation for that release is already up to date

### Budget
This is a full time job. The extent to which this has to be driven for impact to be seen early and fast would need strong commitments and full-on dedication.



## Wagtail Documentation: The goals
1. Drive adoption of wagtail.
2. Provide help and support to people adopting the product.

### The User goals
The User's goals can be framed into four (4) boxes using the Diataxis documentation framework
1. They are beginning to learn about Wagtail, hence seeking a tutorial.
2. They want to understand something about Wagtail, hence seeking an explanation.
3. They want to carry out a task, hence seeking a how-to guide.
4. They are in the process of carrying out a task and want to verify the correct use of a particular widget, hence seeking a reference.

![The Diátaxis framework - credit diataxis.fr](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/df7man12b6q6wdgf3weu.png)
Wagtail is however making substantial effort to align its documentation to this frameworks as can be seen on [Wagtail user guide](https://guide.wagtail.org/en-latest/).

It has a perculiar challenge as quoted in [the challenge](https://github.com/wagtail/wagtail/wiki/Google-Season-of-Docs-2023#our-challenge)
>We have a lot of strong initial interest in Wagtail both from *developers and business stakeholders who are looking* for open source alternatives to a proprietary CMS.

1. Challenge 1 - The People that are looking: Devs and Business people.
2. Challenge 2 - Where they are in their buyer's journey




## General Critique (Friction Log)
I absolutely love how the [Wagtail's Getting Started] (https://docs.wagtail.org/en/stable/getting_started/tutorial.html) guide was initially laid out. It began by giving *one line commands with a bold header* helping me quickly build momentum.

![Image 1: Specific one line commands with headings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/atf72836p59y7jxo1wid.png)

As a developer, If I want to quickly pace through this guide, I only need to look at the headers and the commands, copy and paste them and move on. This maybe because, as a Django dev, I already know what those command mean and do, hence it is not essential for me to read the details. It may also be because I don't care enough to read, I just want to get to the final output, or I am highly pressed for time to show some productivity.

### Log 1: Guide is too long
This guide is too long or the content on this page is long to all be on the same page. This is a problem because:
1. It does not enable Wagtail track which phase people are and where they drop off. If it is broken up into smaller pages - e.g. Part 1/2/3 etc, then we can tell that 50% of the people did not proceed from Part 4 to 5, hence knowing where the bottleneck is at.
2. It does not allow for easy follow on. As a developer following through on the guide, I hate the fact I have to scroll down to somewhere on the page, whenever I come back to it. I hate the fact I don't know where I was and have to spend mental energy comparing my project to each step of the process, because I couldn't just bookmark it.
3. Providing bitesize chunks, that proceeds to the next page, provides some form of motivation to continue, since it seems like progress more than scrolling downwards. 

If the tutorial could be gamified a little bit, makes it all the better. Providing some form of user engagement is essential to learning. See an example from [How to GraphQL](https://www.howtographql.com/graphql-python/1-getting-started/)

### Log 2: Destroying the UX
Despite the super long how-to-guide, I was flowing beautifully, just looking at the headers and the commands. It got to a point where the beautiful momentum, that has been building up is broken, destroying the User (developer) experience.

As can be seen in the image below, the guide does not maintain the bold headers and dark background commands, but changes that to red sentences.


![Image 2: A mixture of commands](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ygcm3l0bxwrsrmuc20s0.png)

For newbies, this might create a slight confusion of _where do I run this command?_

For oldies, it definitely has slowed me down! Since I would have to read the entire paragraph, which I either don't want to or don't have the time to.

### Show Git Diff
As a developer, I use git a lot (who doesn't), and how bewildering it is when I am quickly pacing through this tutorial, especially just copying and pasting code and I meet this


![Show git difference on adding BlogPage to BlogIndexPage](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e6vz50szuaklmyfhiehd.png)

It is also important to show the difference to a page or file - showing what is new addition to that page/file so that persons who _copy and paste_ can quickly follow along seeing what has changed and where.



### Diataxis: Theory vs Practice - Wagtail User Guide
As a Master's student, I have come to appreciate the difference between theory and practice. In sciences most theories are not practiced as theorized. Mostly because theories are based on Standard Temperature and Pressure - they are lab based. However, all practices have an underlying theory upon which they're based.
>Practices are nuanced form of a specific foundational theory

The Wagtail user guide is a good attempt to apply the principles of [Diataxis](https://diataxis.fr/) technical documentation authoring framework. 

![Wagtail User guide](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5lf86w6zma4fb9e3u0e8.png)

However, having studied and thought deeply about it, I've got questions about how it is being applied to Wagtail:
1. Does it need the content to be broken out into the four different forms of the framework?
2. Can a single page contain all four - but using either text styling, font weight, headers, etc to differentiate all four parts?
3. Where in the user journey, would a develop need to reference something, prefer a longer explanation of another, etc?
4. Would it be beneficial to build a dictionary of Wagtail? Given that the dictionary would become a reference.



### A Reference to the Zen of Wagtail 
The Zen of Wagtail defines four users: the content author, site administrator, developer and designer.

![The Zen of Wagtail](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vn4nb12cn0qfvscqtedk.png)

Having recognized these 4 users from the Zen of Wagtail, does the documentation define or describe: 
1. Who - the guide is for? Is it for: the content author, site administrator, developer or designer?
2. At what stage of buying journey is this person? Are they trying it out to compare it with something else? Or on a committed journey, needed some good reading digest.


From the guide
>You can’t make a beautiful website by plugging off-the-shelf modules together - expect to write code.

It wouldn't appeal to anyone who is a content author, comparing content authoring tools.

Whilst the breakdown of users might appeal to larger organizations, 
>We have a lot of strong initial interest in Wagtail both from developers and business stakeholders who are looking for open source alternatives to a proprietary CMS

It doesn't define the amount of dev effort that would be needed to see a page to simply author and publish content. Hence doesn't compare well for there's no way to measure the effort.

Hence failing from lacking clarity and not from being bad.


### Unhelpful feedback
What should the technical author make of this response from the bottom of the page on the guide? Either positive or negative is both bland.

![Unhelpful feedback](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7emq4cv5ss7szvgib6br.png)

I believe using the [Linguistic Theory](https://ubuntu.com/blog/humans-may-be-rational-or-how-to-collect-better-documentation-feedback-with-linguistic-theory) would be tonne more useful than this.

Apply this theory would also have to be nuanced to the product vision of Wagtail. However, this theory forms a good basis to build on.




## Prioritizing what, who and how to write
We don't have infinite resources of time, energy, money, etc. Hence building a strategy should prioritize the right things over time:

1. What - Dev docs
2. Who - Devs
3. How - Technical language: with a depth from simple (for beginners) to complex (for architects and core devs)

The first 6 months would be targeted at these.

Using the principles of good [design docs](https://refactoring.fm/p/design-docs) - is creating the MVP of docs: MV stands for *Most Valuable* and *Minimum Viable*

![Design Docs MVP map](https://substackcdn.com/image/fetch/f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fc6222b87-4a4d-477a-bac6-a58e70a4c2e1_2012x1338.png)

And to really engage devs is to use David Pink's framework from his book - Drive:

* Autonomy — the desire to be self-directed
* Mastery — the desire to improve our craft.
* Purpose — the desire to have a positive impact.

A documentation written that shows possible paths and allows devs to determine how they want to travel.

A documentation that allows devs to determine the level of mastery (or complexity)

A documentation written, aligned to their purposes. This is how to lead an engineering transformation through well written documentation.