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.
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.
No comments:
Post a Comment