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:

Salesforce DevOps - can you get away without knowing git? - part 2

This is following on from yesterday when I got a work item to review stage. Today I've found that you can ignore the pull request in git and work entirely within the DevOps interface to move that work item to the next stage in the pipeline.

I hit a problem with the deployment initially as there was an error in the XML for a report layout (duplicate column*). I had to abandon that work item, as I couldn't find a way to move it back through the process, to uncommit the changes and then commit all the files, apart from the troublesome one.

I also made a rookie error - you have to deploy profiles in order for newly created fields to be visible on the profiles you want.

Concepts

Here are the concepts I think you need to be comfortable with in order to be able to work through this process.

The stuff in setup is metadata, which underneath it all is a tree structure of XML files. Without really understanding the ins and outs of XML you need to be able to spot things like - this file defines a new custom field.

The tree structure follows familar concepts like objects, report layout and profiles, as well as more obscure things.

The deployment process is essentially updating those metadata files by copying them from one environment (i.e. Salesforce org) to another.

The pipeline defines the order of environgments that work items move through.

I think the word pull used in the work item and in the pull request doesn't need to be fully understand, but you do need to get this: for the first it's the things that might have changed that you want to include in your work item. For the second, it's the things that have changed that you want to move through the pipeline.

* Surely this must be a bug in Salesforce? If a valid report layout can't be deployed then there must be something wrong with the way the XML is created.

Salesforce DevOps - can you get away without knowing git? - part 1

Here at Wycliffe we've started looking into Salesforce DevOps Center [sic] and I've been doing some investigations. If you're a dab hand at DevOps in general then this isn't for you. If you've heard of it and want to know more then read on.

This step by step tutorial is a good start. My observation is that, for whatever reason, in the past Salesforce didn't give much attention to the deployment process with Change Requests that were a bit faffy to use. So third parties developed their own tooling, and now Salesforce with their own DevOps Center are trying to catch up with those third parties.

One question I had as I actually started using DevOps Center was whether you needed to understand git, or could you just get by with mostly ignoring it. When you set up DevOps Center you need to associate it with a git repository, so you have to at least interact with github.com. After that though, you can carry on, even though you don't really know what a branch is.

However, when I wanted to put my work item up for review, there was no more escaping:

The rest of my team haven't used git, though one has worked through a tutorial. My challenge is to try and lead them through the process and see if we can get by with understanding just the bare minimum of how git works. I'll write more posts about that as I explore.

Bonus link via Julia Evans, why Git is hard.