Tips fo Writing Good Documentation

Technical
1

Generally, I try to prepare the material with the mindset of: “If I was a complete beginner or user to the system, what would I want to know and what should I need to know?”

Of course, if you’re not careful you could run into a rabbit hole where you’re putting in too much information or explanation in the documentation which could extensively lengthen it.

I have seen cases where documentation has been written with the assumption that the user has some other documentation. I think in such instances it is very helpful to include your assumptions at the start of your documentation.

What do you keep in mind when writing good documentation? Drop your tips in the thread

2

This is a good shout :+1:t5:

  1. Being specific about the intended audience
  2. Getting it proof-read by representatives of said audience
  3. Using spelling/grammar checkers
2 Likes
3

I definitely agree with the second tip. I think that’s something a lot of people seem to skip over. It’s basically like testing in software development.

1 Like
4

It’s also ideal to be conscious of how much you really need to explain to the target audience, so that you only write what you need to. Otherwise you’re just creating more work for yourself both now and in the future, when software changes invalidate the documentation.

2 Likes