Technical guide

From OpenStreetMap Wiki
Jump to: navigation, search

This page should explain what you should and what you shouldn't do when writing technical guide.

How to create actually helpful content

Recommended read: Wiki_guidelines#Focus_on_usability.

Endless FAQ pages, they are wasting everyone time: hard to write, hard to update, hard to read, hard to update translations from, hard to sync, hard to link, hard to update page without breaking everyone else links.

Guide your users:

  • per goal, per task
    • Explain in terms of latest supported, tested and ready-to-use version, move irrelevant notes to separate pages
  • per troubleshooting symptom

Use more maintained resources outside this wiki

Keep readers focused

Recommended structure of subpages

Recommended read: Wiki_guidelines#Structure. TODO: add template with common translated names

  • /Installation - overview of required components, environment-independent instructions
    • /Installation on system X - same as above, but more focus on environment-specific, you may warn users with "Please read /Installation first" here
  • /Use cases - "Why and when anyone wan't to use this guide and software?" "Conditions?". Explain software in terms of:
  • /Features - (not a technical guide!) similar to above, but less technical view, end-user content
  • /Limitations - in technical terms: engineering trade-offs, decisions during development and so on
  • /Troubleshooting - aka "FAQ" page, try to not bloat this page, split content per task, per environment and so on. Review Category:Tool X once again and update additional references and "See also" sections.
  • /Benchmarks - will be only relevant for IO heavy tools and tasks

Good examples

Wiki labels to maintain guides

Expand requests

Update requests

Reader feedback

  • works for me
  • environment
  • comment or other free text (performance reports for ex.)