Applying Diátaxis to a specific project

Diátaxis is a really interesting approach to technical documentation. It's summarised well in this paragraph and diagram from the website.

"Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs."

I recommend digging through the site a bit before you carry on. Don't worry, I'll wait.

Glad you made it back.

I've been thinking of applying it to our existing technical documentation but never known where to start really. However an opportunity came along to apply it to a specific need.

The need: URLs for campaigns

We want to run campaign across print and digital, which direct people to pages on our website. We want to track how people respond to those campaigns, including on Salesforce where the information about people, signups and donations ends up. The knowledge about how to create URLs on and for our website, specifying Salesforce campaigns, and tracking results through Google Analytics is spread among various people. We had a meeting planned to share knowledge and ahead of time I wrote a document capturing my knowledge. I'm not going into the details of the information, as that's specific to this problem, but rather the process.

Here are the headings I used in that document:

• Tutorials
• How-to guides
• Creating redirects in Wordpress
• Tracking campaigns for web forms
• Tracking campaign segments for web forms
• Tracking social referrals in Google Analytics
• Explanation
• Redirects
• The stuff after the question mark in a URL
• Reference
• Web forms in use and default campaigns

As you can see there is nothing at the second level for Tutorials, as at the moment I can't think of what a tutorial would cover. However I may come up with something after the meeting. It would be something useful to someone who knows nothing about the subject.

I may put more in this post after the meeting, but I thought this worked example of applying Diátaxis would be useful.