Tribeless Nomad (tribelessnomad) wrote in lj_userdoc,
Tribeless Nomad
tribelessnomad
lj_userdoc

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.
Subscribe

  • FAQ232

    There is a typo (or two) in FAQ232. I'm talking about the following sentence: Ddd them to your Friends list them with the Add Friend button at…

  • New FAQ: How do I deal with spam?

    This FAQ is meant to tie together all of our spam-related information, currently spread over several different categories. Ideally, I'd like to have…

  • Identity Account FAQs

    As LiveJournal Support regularly uses the term identity accounts both in answers to users and amongst themselves, and some system pages refer to…

  • Post a new comment

    Error

    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 

  • 0 comments