What is Documentation Design that I haven't already done?


I'm a contractor who has been working on a project (a developer guide website) for months with another contractor writer. We spent a lot of time:

  • Interviewing end users
  • Designing the deliverable (creating an outline and defining content, demos, example source code, etc.)
  • Establishing styles, standards, and procedures
  • Fine-tuning them
  • Performing Proof of Concepts
  • Running it past our interviewees
  • Tweaking our work
  • Prioritizing the work
  • Creating a first release

They let my co-worker go and replaced her with a full-time employee with an inflated ego. He says the documentation was not "designed," and when I asked him what he meant, he couldn't articulate a coherent answer.

Does anyone have a clue what he might mean by "design"? Maybe a template? I searched the internet, but all I come up with is design documentation, which means something entirely different.

Why should this post be closed?

This post was sourced from It is licensed under CC BY-SA 4.0.


1 answer


I have no clue what he meant by designed. But I agree with him that you have not designed the documentation.

Why? Because you have not created a list of user tasks.

Documentation is a response to a theory about what users want to do. Its purpose is to assist them in doing the things they want to do. If you don't have a theory about what users want to do, you don't have a useful documentation design.

Of course, this can be difficult. Interviewing end users is a start, but what did you interview them about? What you want to know from users is: what tasks do you want to accomplish, what do you know now, what do you call things, and how do you do those tasks now (if you already do them)?

That is the information you need to write documentation that assists them in doing the things they want to do. If you don't have that information and a plan to provide it, you don't have a documentation design.

Now it is true that your documentation will have to use a particular font for heading and for body text, and it is not a bad idea if you are consistent in a bunch of stylistic questions. But these things are just the design of the document, not of the documentation. It's fine to have that stuff, but it does not tell you what tasks you are supporting and how you can best support them.

To design the documentation, you need a theory of the user's tasks and of who they are, what they know, and how they currently do things, and a plan to support them in completing their tasks in your tool. Till you have that, you may have a document design, but you don't have documentation design.


Sign up to answer this question »

This site is part of the Codidact network. We have other sites too — take a look!

You can also join us in chat!

Want to advertise this site? Use our templates!