Writing Guidelines is Easy...

No it is not! Thoughts from my journey into guideline purgatory.

So, here I am sitting, writing the guidelines for data buyers on the TIKI data licensing platform. I set out to write this two weeks ago and thought I would finish it in a day or two.  Oh, how wrong was!

On the surface, writing something as straightforward as the Apple App Store Guidelines looks relatively easy. Let me tell you, it is not. I have learned a lot while writing and researching how to go about this. Here are a few of the things that I have learned along the way.

I started by looking at several platforms and service providers' guidelines or “rules.” I pretty quickly discovered that the term “guideline” is a misnomer. They are generally the rules or codes of conduct for companies. A good example of this is Unreal. If you scroll through their guidelines, they read more like a set of constraints or parameters. For the sake of the article, I will persist with the term guidelines.

Some platforms take the concept of guidelines and add self-support, guides, and rules on what is permitted. Facebook does this in a way that does not make it feel like a set of instructions. They mix a few other elements to make it feel a bit “softer”.

Some companies use a very forceful tone and language in their policies. Is this an attempt to intimidate the reader into thinking they have stumbled into a legal document? Microsoft uses this type of language in their policy documents. It feels very legal, and if you read the Harvard Writing Guide, it advises the writer “to write for the user first.” It makes me wonder if the Microsoft authors were intentionally writing to have that effect.

The logical flow of the topics in the guidelines can be interesting to read. You would assume that the flow would follow life, birth, death, and taxes. Hubspot does an excellent job of outlining the flow. They take a developer through the life cycle of an app, from why you should list through to the review process. Strapi does a nice job with this too. They follow the “Why, How, and What” sequence. Compare this with the SEC and the way they present their rules and regulations. This is unintelligible to a newcomer or somebody who does not know what they are looking for. The reader should be able to follow the flow in the document headings and relate to them. In our case, we define an offer and how a buyer goes about making an offer to a user. We then follow with the user's operation of the exchange or license to the company and the agreement's lifetime.  

Some guidelines can be very complex and hard to navigate. Amazon is in a lot of markets with different marketplaces for many types of stores, the policies for this could be a complex mess, but they do a very elegant job of presenting them in a clear and cohesive manner. CME also do a nice job of presenting a vast set of rules and regulations by linking the heading to each chapter. On the other hand, the Bored Ape Yacht Club have listed their policy documents in what appears to be a random manner.

So, what have I learned from all this? I need to think like a company that is looking to strike a deal with a group of users and to think about that logical sequence.  The person needs to understand what they can and can’t do but also need some guidance to help them in how they make the offer. Language is very important and how you word the guidelines is something that needs a lot of effort not to sound too draconian. I also need to think of the presentation of the guidelines and how somebody reading them for the first time will engage with them. The need to make sense and be a reference point for the experienced to revisit. The set of guidelines that I aspire to is, as far as I am concerned, the gold standard, the Apple App Store Guidelines.