Wiki:Technical guide

From OpenStreetMap Wiki
Jump to navigation Jump to search

This page explains how you should write a technical guide in this wiki. Endless FAQ pages are wasting everyone time: hard to write, hard to update, hard to read, hard to update translations from, hard to sync, hard to link, and hard to update the page without breaking everyone else links. This page provides alternative approaches to technical guides in this wiki.

How to create actually helpful content

Main article: Wiki guidelines
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
Consider upkeep
Link to other pages
  • providing your sources helps readers, too
  • official docs, including one of the best in industry
  • Well explained "See also" sections at the bottom of each page. What next? What else should I know?
  • Categories help to group pages and find similar ones

Recommended structure of subpages

Recommended read: Wiki_guidelines#Structure. If pages get to long, you might want to split the content over multiple pages. Remember to guide your readers. Otherwise they will not find the pages. The following is an old suggestion for rather long technical guides:

  • /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

Related categories

Category:Technical guide
general super-category for a kinds of guides (should be moved to sub-categories thereof)
Category:Outdated technical guide
guides that need to be updated
Category:Guide
guides or tutorials, mostly non-technical content for mappers