3 ms·

When I'm writing documents for whoever touches a system behind me, I write wiki articles on what the system is/does, logical data flow diagrams, and a deep dive

When I'm writing documents for whoever touches a system behind me, I write wiki articles on what the system is/does, logical data flow diagrams, and a deep dive into whatever it was that I just touched. From there, I make a condensed narrated PowerPoint with pretty charts and UI element screesnhots. If I have bonus time, I might even make a basic Chamilo course to cover the application and immediate dependencies and ecosystem. This all sounds great to write, but I wonder how much of the work actually gets used. The devs that wrote the program often don't bother with documentation (fail fast and fail forward!) so I have at least a small sense that wiki searches etc will surface my material, but I wish there was a better way to track who found what useful or not without them walking up to me and personally commenting on it. Suggestions to up my documentation after the fact game are welcome.

sicher 8y ago
I have worked extensively on the documentation for the Defold game engine (see https://www.defold.com/learn/ https://www.defold.com/learn/). Here's a few things we've done: We use Google tracking on the site. That helps a bit. We have search available on the site and we get the most useful information from how people use the search function. We get clues as to what users are looking for, what terminology they use and I use that to make sure common searches turn out good information. I added a "Have a suggestion?" button at the bottom of each page. You have to be logged in to see it (because of bots) but it allows you to mark text directly on the page and then report errors and suggestions. We get a lot of feedback through it, much, much, much more than before when we relied on users sending their feedback or stopping by to talk.
- andygcook 8y ago
  Good instincts on the suggestions feature idea. My startup builds internal documentation software. We built that exact feature and our customers really like it. The problem with most documentation is that it goes out of date. Wrong docs are often more detrimental than no document at all. Allowing readers to flag information that might be wrong, or even suggest an update to merge, helps to harness a team’s collective knowledge to keep documents updated.
reacweb 8y ago
As a programmer, when I write documentation I try to make this work profitable for me. First, I open the specifications I had and I try to describe how it was implemented. Often, this means I have to give a look to my code or tests and this makes me identify a bug or a missing test. I try to be concise and to avoid repetitions because big documentations are more expensive to maintain. At the end, I try to imagine the future me who will have completely forgotten this project and will be asked questions by users who will start using it. When I finish a project, I free my mind of all the details.

sicher 8y ago

I have worked extensively on the documentation for the Defold game engine (see https://www.defold.com/learn/ https://www.defold.com/learn/). Here's a few things we've done: We use Google tracking on the site. That helps a bit. We have search available on the site and we get the most useful information from how people use the search function. We get clues as to what users are looking for, what terminology they use and I use that to make sure common searches turn out good information. I added a "Have a suggestion?" button at the bottom of each page. You have to be logged in to see it (because of bots) but it allows you to mark text directly on the page and then report errors and suggestions. We get a lot of feedback through it, much, much, much more than before when we relied on users sending their feedback or stopping by to talk.

andygcook 8y ago
Good instincts on the suggestions feature idea. My startup builds internal documentation software. We built that exact feature and our customers really like it. The problem with most documentation is that it goes out of date. Wrong docs are often more detrimental than no document at all. Allowing readers to flag information that might be wrong, or even suggest an update to merge, helps to harness a team’s collective knowledge to keep documents updated.

reacweb 8y ago

As a programmer, when I write documentation I try to make this work profitable for me. First, I open the specifications I had and I try to describe how it was implemented. Often, this means I have to give a look to my code or tests and this makes me identify a bug or a missing test. I try to be concise and to avoid repetitions because big documentations are more expensive to maintain. At the end, I try to imagine the future me who will have completely forgotten this project and will be asked questions by users who will start using it. When I finish a project, I free my mind of all the details.