Wagtail: Engineering transformation through documentation

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

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 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 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.

Wagtail is however making substantial effort to align its documentation to this frameworks as can be seen on Wagtail user guide.

It has a perculiar challenge as quoted in the 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 guide was initially laid out. It began by giving one line commands with a bold header helping me quickly build momentum.

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

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.

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

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 technical documentation authoring framework.

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.

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.

I believe using the 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 - is creating the MVP of docs: MV stands for Most Valuable and Minimum Viable

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.