Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs

Dashboard
Notifications
Mark all as read
Q&A

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

+3
−0

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 does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/48383. It is licensed under CC BY-SA 4.0.

0 comment threads

1 answer

+3
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »

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

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate