Documenting your Project

One of the creators I support on Patreon, wrote a post about how it is hard to write documentation.  And I have to agree, it is often the worst part with any project that I’ve had to deal with.

There are a few different parts that I think a lot of people fail to understand about documentation.  There are certain goals that you want to accomplish and that’s a lot more difficult when you don’t understand that you have to separate different types of documentation.

There tends to be different divisions that people talk about depending on what the focus is.  If we’re talking about something like an open source project one division would be:

  • Marketing material
  • User material
  • Developer material

I would say this is a fair division, but it really isn’t breaking it up in terms of how the documentation functions.  I’m taking a bit of a stab at this in terms of functional purposes:

  • Technical specifications
  • How to instructions
  • Component documentation (man pages?)
  • Philosophical documentation (why things are the way they are)

To be functional in terms of technical writing, and actually being useful, you need to separate these things out.  I’m not really that great at figuring out how to do that, as I tend to muddle stuff together kind of naturally.

A good way to understand if the documentation is good is when someone asks, “how do you do X?” can you point easily to a how-to about how to do exactly that, or say, “That’s a bit complicated, and you need to look at this manual which explains the details of programme Y?”  or, “You are trying to interface programme A with programme B, and you’ll need to look at the specifications for the API of both of them here… and here…”

If the go to answer is, “look at this 90 page document and that explains that one simple thing” then first off the documentation is poor, and there is a culture that it doesn’t really matter that the documentation is poor.

I’d really like to say that I feel that what I’ve said here is useful, and will help people figure out how to do good documentation.  But I think at best, it might be helpful to realize that the reason that the documentation isn’t “working” is because it actually isn’t good documentation.

Maybe?  If I broke down those bullet points, and found ways to talk about what they end up meaning it could prove helpful.  I feel that each of those 7 bullet points could easily be at least as long as this, to come up with a good starting place to work with them.  Possibly breaking further into similar numbers of similar sized pieces.

This would be a decent start to consider going further with this…  If someone else wants to do so, or whatever.  Maybe some time if someone contacts me (however they would) about something they’d like to hear me say more about, that I’d expand this out…

This entry was posted in Uncategorized. Bookmark the permalink. Both comments and trackbacks are currently closed.