Tribeless Nomad (tribelessnomad) wrote in lj_userdoc,
Tribeless Nomad

Writing maintainable documentation

I'm addressing this to nilesta, because of the new project she's starting, but the same principles should be observed by everyone moving into editing positions.

If you've watched how suggestions in this community are approved, rejected, or modified, you may have noticed the following themes recurring.

1. Nothing should be documented in more than one place unless it's absolutely necessary. That's an ideal, not a goal we can really achieve. It's important, though, because no one wants to rewrite multiple documents whenever a single procedure changes. (Nor should users have to read the same thing explained three different times.) That's one of the main reasons I respond so cautiously to new suggestions and spend so much time deliberating what goes where. As you put the Volunteer Center together, you'll need to struggle with the same problem. Many facts do have to be mentioned in several different places, but don't repeat an explanation, or a detail that might change, if you can figure out how to use a link instead.

2. Don't write documentation that won't be kept up to date. You shouldn't put anything in official documentation unless you believe someone will update it when the facts change. One reason we don't have more customization FAQs is that it would be too difficult to update them all when changes are made to the site. You'll run into similar problems if you try to document aspects of volunteer activities which are subject to frequent, sudden, or unannounced changes.

  • Post a new comment


    Comments allowed for members only

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded