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.

  • FAQ 290 Way Out Of Date

    FAQ 290 thinks the latest version of the iOs app is .6 and does not mention that there are apps for Android, Windows Mobile, or Bada, all of which…

  • Extra character in hyperlink

    There's a semicolon that accidentally got incorporated into the URL in FAQ 187: the "Manage Pubkey" page […

  • Account Types

    FAQ38 does not include a mention of Sponsored Accounts.

  • 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