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.

Being more organised is less fun

I've been using OneNote alongside Outlook for the past few months. It's really handy and a great way of managing my todo list. A while back my todo list was an email that I'd keep in the drafts box. Then I switched to tiddlywiki. With OneNote I can achieve a frightening level of organisation. I type something into OneNote, and press ctrl+shift+3 and a task is automatically created in Outlook for this thing to be done by the end of the week. With OneNote I can see things laid out in four dimensions (two dimensions on the page and then two other dimensions with Notebooks and tabs within them). With Outlook I can see things organised by due date.

Each day I can review the tasks to be done and either do them, or defer them to the next day, later this week, or next week depending on priority. When things are awaiting on other people I can add a symbol with a keystroke to show that I don't need to do anything more with it, and I can see a list of those waiting things from OneNote.

(It may even be possible with a bit of programming to get tasks lined up with even more accuracy. My computer could say to me "you've got 15 minutes before lunch and an appointment straight afterwards, so here's your next task that shouldn't take too long - write a blog post". Or "you really ought to be going home now, and you're probably a bit tired - why not do a little bit of light document editing and then go". )

But I find that the more organised I am the less fun things are. There is a brief moment of satisfaction when I press ctrl+shift and number key as I know that I don't have to do anything else to make sure I get a reminder. Ticking off tasks as done is also satisfying for a second or so. But it doesn't last, I'm back to a list of things arranged in order of importance that have to be done. It means that I'm more effective and important stuff gets done first, but it's a bit soul-less.

I've been thinking a lot about games recently. There's talk on the interwebs about bringing gaming elements into tasks to make them more enjoyable. There are people who are trying to develop games that teach you things, like Smokescreen which teaches about on-line privacy. I've also been reading my son's Official Nintendo Magazine and a couple of articles about bedroom games makers, of which I was one in my teenage years.

What I'm wondering is how I can continue to get important stuff done, and have fun doing it?

Using media wiki for internal documentation

Many months ago I did an update on my quest to find a wiki for doing internal documentation.

Here's another update, following an installation of media wiki.

Even though I've edited pages on wikipedia, which runs on the media wiki software, it was useful to do an installation to get a flavour for what it might be like using it for real. The system I'm moving away from is a Lotus Notes out-of-the-box "document library". When I started editing wiki pages it made me realise what Lotus Notes gave me as standard:

• WYSIWYG editing
• ability to paste from formatted Word documents and retain formatting
• automatic compiling of table of contents
• easy linking of documents
• easy embedding of images

Apart from the internal reasons for switching away from Lotus Notes I had to remind myself of why I was doing this:

• easier access for remote users
• email notification when a page changes
• version history maintained

The problems with embedding pictures is something that web applications haven't overcome as far as I've seen.

Our corporate wiki software has good help with linking and allows the creation of child pages, and can do a resulting table of contents of child pages. It also does WYSIWYG editing.

Pasting from Word documents is a double edged sword. I've seen another WYSIWYG editor that allows it, but gives you the resulting horrible HTML that goes with it. Wikis don't tend to do that because of the difficulties in converting to the underlying wiki format. Why don't I use our corporate wiki you may ask? Among other things, its because procedure manuals don't fit with what the wiki is for.

One thing that I have got working with media wiki, is linking the logins to our Active Directory, to save people having yet another login.

So the question is, can I put up with a couple of shortcomings for the good things it does? Time to see how other wikis compare I think.

Visting Raiser's Edge users

I've just started a project to visit all the Raiser's Edge (RE) users in our organisation. I'm doing it with several purposes:

• Make sure that people know where the procedure manual is and are following it.
• Seeing if they have any suggestions about improving it.
• Seeing if they have any questions about RE that they wouldn't normally bother me with, but while I'm there, they could ask me.
• Seeing if they need any training in specific areas of RE.
• Seeing if they need IT training generally.

One of the things I'm wrestling with, and I hope to get clearer on, is how to impart information about something as complex as RE. I touched on this on my post on skills in procedures. Off the top of my head I can think of various skills that you need:

• adding things to a list in a grid
• deleting lines from a grid
• adding things to a list which isn't a grid (add button at the top)
• switching between records using the arrow at the top, or the menu, or the arrow at the top with a dropdown

I think the trouble with teaching these is that people don't want to learn how to do things, they want to learn to do things. If they want to add information to people's records and I start teaching them to flick around then they are going to get frustrated.

One of the things I'm going to revive is the sending of weekly tips to impart this sort of information. I'll post them here too.

Using a wiki for procedures

A while ago I blogged about using a wiki for your procedures.

I've been using jumpbox list of wikis to evaluate some. Here are my initialconclusions (based on comparing the writeup with my requirements):

pmwiki
I particularly like two points from their philosophy:

1. Favor writers over readers
3. Avoid gratuitous features (or "creeping featurism")

tikiwiki

TikiWiki is your Groupware/Content Management System solution with a long list of features to help you build a compelling web based community: Wikis, Forums, Blogs, Articles, Image Gallery, Map Server, Link Directory, Translation and i18n. And much more...

Too much

moinmoin
Looks promising.

twikiwiki (Watch the extra w)

TWiki is a flexible, powerful, and easy to use enterprise wiki, enterprise collaboration platform and knowledge management system. It is a Structured Wiki, typically used to run a project development space, a document management system, a knowledge base, or any other groupware tool, on an intranet or on the internet.

Too much

mediawiki, as used by wikipedia
Promising. Slightly too much stuff on the page, but can be configured away.

docuwiki
Specifically designed for creating documentation, however you can't get email notifications when a page changes, which is a showstopper for me.

So that's three to look at. I haven't evaluated them on ease of installation, or maturity of product, or how much support there is, or how widely they are used. More to come...

Update: 17 March 2009 on using mediawiki for documentation

Ding! Procedures need skills

I was just doing some training on a procedure that I've written.

One of the things I've struggled with is what level to write them at. Which do you say?

refresh the spreadsheet

or

right click and choose "refresh data"

or

push the right hand button on your mouse. A menu will pop up. Move the mouse down until the line "refresh data" is highlighted and then push the left hand button on your mouse

.

What I just realised in a flash of inspiration, was that things like right clicking and choosing an option, or refreshing spreadsheets are skills that apply to more than one procedure. You don't need to give instruction on the skills in the procedure, but it would be worthwhile (even though a lot of work) to list the skills required to do the procedure. Then when teaching someone how to follow the procedure, you don't really teach them the procedure, you make sure they have all the skills to do it, and leave them to get on with it. A well written procedure will not need teaching if someone has all the required skills.

This is probably all in the standard textbook on procedure writing, but I don't have such a book.

Procedure writing and post-it notes

For a while I've had it on my mind, and low down on my to-do list to move our procedure manual, currently in Lotus Notes, to a different medium. Some of the criteria were:

- easily editable
- hyperlinking between documents
- web accessible
- version history maintained
- looks good when printed
and this is the one that distinguishes options
- users emailed when procedures they are interested in change

My conclusion has been to use a wiki. What I'm trying to get people less dependent on paper - though the "looks good" criteria recognises that it will never be got away from, certainly while not everyone has two monitors.
One thing paper procedures are good for, is when I've changed something, and I want to test that it worked in the real environment. In this case I email them saying "give me a shout when you get to step n". They put a post-it note on the appropriate point, and give me a shout. What I now need to think about is a good way of doing that, which is easy for all concerned.

Today I have mostly been writing procedures. Procedures are our lifeblood, but you can't get away from the fact that they are boring. Like with programming, test driven development, would have been a good approach, but I didn't think that it might apply to what I was doing before I started. However I will be writing tests next, as the thing that the procedure is covering (Direct Debit) could get complicated.

Writing procedures is a bit like programming, but what you can't be sure is how your "compiler" will treat the "code".

tags: tdd