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.

I was suspended on Twitter for no apparent reason

I try to avoid moaning too much on Twitter, but I've been suspended, so I'm going to moan about Twitter here. A few days ago I got a message that I'd been suspended. The last thing I tweeted was to retweet this picture:

It's not so straightforward though. As well as telling me I was suspended it also said I could subscribe. Sometimes I can see my old tweets, sometimes I can't. Sometimes I can see people I follow, even though it says I am following no-one, sometimes not.

What could I have done? I have several theories:

• I liked a post I shouldn't have. As I can't get at my likes I can't check this.
• My bio ("I ride tandem...") somehow breaks the rules.
• I mentioned my mastodon id.
• I called it Twitter and not X.

I've tried asking for a review, but as soon as I fill in the form I get a reply seconds later saying that they're not going to re-instate me. I do have a second twitter account that I set up, so I can still use that. It shows that it's probably worth creating a second account just in case you get banned in future.

Preventing duplicates from FormAssembly in Salesforce

Just a quick one.

When using FormAssembly (FA) with Salesforce that if you had a duplicate rule set to alert, then that would cause an error message to appear on the form. FA would treat this as a failure and not proceed. 

I submitted a suggestion to them that they treat duplicate alerts as warnings and not display them to the user, but I couldn't get them to understand what I meant.

So we have to handle duplicates after the fact, with a daily check, using a Google sheet that we wrote that looks up email addresses.

Syncing people data between systems - why is it so hard?

Although some people write weeknotes I've never done that because I think what I've got to write about is too internal, or not interesting. However I'm writing about a work problem, not because I've got solutions, but to help me step back and think about it, and maybe get answers from you, dear reader.

Over the years I've been involved in getting data about people in sync between the HR system and the CRM (specifically a donor management system). You might ask, "why are staff on the CRM?". Staff can be customers, or in our case, donors. In particular, we would track potential staff ("enquirers") because the HR system didn't.

Here are some of the challenges I've had with the process:

People data is messy

Names in particular are messy, so when checking to see if two records are for the same person then it may be hard to work out. Systems tend to have unique ids, so storing the id of the person that the other system uses on this system gets round that. Until the member of staff makes a donation and spells their name slightly differently...

Addresses are messy too. In the UK there are unique DPSs, but validating incomplete addresses is more of an art best done by people, than a science at times.

The HR system isn't always definitive

I created a sync process that would compare the HR and CRM systems and highlight differences. When I created it I suspected that it would be unwise to assume that the HR system was the definitive source of truth, even though it was in theory, so the sync process would only highlight differences, not automatically update the CRM to be the same as the HR system. This turned out to be correct, and the process ran for several years, once a week, and most weeks there was something for someone to change on one of the systems manually.

Different definitions of people

You would have thought that all systems have the same definition of a person, but that's not the case with the sync method I'm using that's driven me to write this blog post. We use Salesforce as our CRM, and send out bulk emails with Campaign Monitor. There's a Salesforce App from Beaufort12 that synchronises data between the two systems. We have some couples that share an email address and so what Campaign Monitor treats as a unique subscriber corresponds to two different people on the CRM.

One consequent of this is that when one member of the couple dies that email address will automatically be unsubscribed and the remaining spouse may want to continue getting emails.

Testing integrated systems at scale can be hard

We don't have a test Campaign Monitor setup, so we're working on the live system all the time. Of course, it is possible to create test integrations in some circumstances, but if you're working with a complex system you may not be able to mimic all its complexity in a test setup.

Conclusion

None of this is has particularly helped me with the Campaign Monitor syncing problem I've currently got, but I hope it helps you with some general advice.

Alice Bartlett - the journey of a byline, and agile comms

 If I'm emailing myself something to note for later then it probably needs to be a blog post. Here is a really interesting talk by Alice Bartlett about the journey of a byline in the FT and their publishing architecture.

I captured this slide though, because it's a good summary of how to do internal technical comms. It's from the agile comms handbook: