Computational Design can be a chaotic process. We often have to use a variety of tools and file types at once. We create what can be a complex data flow between tools to get the work done. This makes documenting the work that we do quite difficult. Not that documentation in any other industry was ever easy, but with the way that we work, it makes it a lot harder.

Take a neighbouring field like software development for example, until now, there is still no best way to create documentation. And I argue that there never should be one because every situation is unique. Good documentation should depend on it’s audience and what information it exposes.

To help us better write documentation, we need first to understand the two general types of documentations out there, prescriptive and descriptive.

Prescriptive Vs Descriptive

The first thing that pops up in our mind when we think of documentation is generally prescriptive documentation. It gives you the steps and tells you how to use the tool/process. Walkthroughs or any step-by-step guide detailing the process is a form of prescriptive documentation. It’s good to ensure people to follow a procedure or process but it limits creativity. If people are just following the steps, they don’t build an understanding or instinct of what the tool/process should be doing.

Then, by contrast, descriptive documentation is about how the process/tool works and why it exists. Different to the prescriptive type, this type of documentation is all bout context and leaves the users to understand the inner workings on their own. Though this demands more effort from the user, it eventually creates a more profound understanding and intuition about the tool/process.

As you may already be able to guess, the “best” type of documentation lies somewhere between prescriptive and descriptive.

Documentation is Recursive

All documentation is recursive in nature. You as the writer get to decide the granularity of the information. For example, if you are writing a step-by-step guide, you will have to choose how “big” each step is.

And if you are writing descriptive documentation, you get to control the detail of your description.

The amount of detail you expose should depend on the type of audience you are writing for. The more knowledge they have in the subject matter, the less you need to reveal. It’s about understanding your reader’s general level of understanding. This may sound like common sense but it’s about being intentional with our documentation.

We can’t cater for everyone, beginners to advance, so we have to assume a base level of understanding. So, before you write anything, consider on the spectrum of beginner to advance, which level will your readers have ? and which level does your documentation target ?

Before we get into a general framework for documentation. I thought it’s a good idea to look at some examples of documentation, both “good” and “bad”.

Good and Bad Documentation

As I said before, the notion of good and bad documentation is different for everyone. So, just take that into mind when reading the next few sections. What I find good or bad is based on my own experience and understanding. It’s okay for your opinion to be different on this because no one person reads things the same way.

The problem I find with most documentation is that it either does too much or too little.
Meaning, it either gives me so much information that it’s confusing and overwhelming or it doesn’t give me enough information to be useful. An aspect of good documentation comes back to it’s intent. As in, what do you want your readers to know after reading your documentation ?

I have found that good documentation is normally a hybrid of both descriptive and prescriptive types. But more than that, good documentation has a good understanding of their reader’s general perception of their tool/process. It uses descriptions to provide context about itself. It uses prescriptions to tell users how to use the tool/process. It even sometimes has examples and aids to help users better navigate their documentation.

Some examples that I have found are :

• Welcome! | Speckle Docs
• New to Notion – Notion Help Center
• Welcome to the Gatsby Way of Building | Gatsby

On the other hand, bad documentation lacks the awareness of their readers. Often, readers feel lost, they don’t know where to find things or how things work. It’s confusing and overwhelming.

Some examples of bad documentation :

• The ETABS API documentation
  • it shows too little to be effective, you can get by with basic functions. But it is missing the intricacies of what certain functions do.
• Technical documentation | Microsoft Learn
  • Shows way too much information that it’s hard to sift through. I am normally sent into a sea of jargon without understanding how it relates back to my problem.
• BHoM documentation
  • Shows too little information about the tool. Has good descriptions about it but not enough for users to do anything with the tool.

If there was a preference between the types of bad documentation. I would prefer to have too much information, at least there is a way to -- painfully -- uncover the inner workings of the tool.

So, gathering what I have learnt from reading good documentation as well as experience from writing computational design documentation for others. I have taken these lessons and consolidated them into a general framework that I now follow.

A General Framework for Writing Documentation

When writing good documentation, I think there are two principles to follow, be intentional and provide context. This means if your intention is for people to follow procedure like installing a program, then the classic step-by-step approach is good enough. Conversely, if you need your readers to understand something but they don’t work with it , then all you need to do is describe the process/tool.

But if have readers that need to understand and use the tool/process, like most applications, then you should follow the hybrid approach. That is what this framework will be about, it’s a way of blending both prescriptive and descriptive elements to help users not only understand the tool/process, but to also effectively use the tool/process in their own work.

As a step-by-step process, this is how I would approach documenting my tool/process. I have use this framework not just for computational design but for documenting any work that I do.

The Process

• Start by being descriptive and lay out the context for tool or process that you are documenting. Tell your readers why they are here and why this tool/process exist.
• Then, we can be more prescriptive , we can start telling them how to use it and the steps to take to achieve a certain result.
• Depending on what you are documenting, it’s a good idea to come up with an example that mirrors real life. But keep in mind that this isn’t always possible and will take some time.
  • If you do have the time, go through your example in a way that is both descriptive and prescriptive.
  • Try and explain how the example is tied to the tool/process, then give the steps and your thoughts while you go through the example.
  • You want it to feel like a mentoring process, like having someone sit next to you and watch what you do with the tool/process
• Finally, end with what marketers use as a “call-to-action”. But instead of getting them to buy or sign up for something. Get them to do something with what they have just read.
  • That could be going through the example that you just gave
  • Or going to another relevant page of the documentation to learn more
  • The point is to not leave your users hanging and give them something to do to cement the information.

So, if I were to write a single page documenting my tool/process. The breakdown would look something like this.

But this framework doesn’t just apply to single pages. If I were to document a large and complex application, I would scale up the current framework. I.e. use pages instead of sections.

The idea behind this framework is to be intentional and to provide the necessary background information. It’s about telling people, what your documentation does, why they are reading it and then finally how it applies to them. I have found that over the years of me doing this, blending prescriptive and descriptive elements helps others build an awareness of the process/tool that neither one type can do alone.

Final Thoughts

Writing good documentation is tricky because it’s unique for every situation and largely depends on the readers. It’s also hard to subjectively measure what makes a good documentation. For new comers to your process, being more descriptive is a good idea but it might turn away more advance users who just want to know how to do something.
That’s why it’s about being intentional with your documentation.

Even though I am an advocate for blending both prescriptive and descriptive elements, if you have an advance user base, you will be better of writing only prescriptive documentation because they don’t need to know the context. The bottom line is who are your users and what do you want them to know.

Thanks for reading,

If you have enjoyed this, consider subscribing to the newsletter.

I’ll see you in the next one.

Braden