Wiki:Technical guide

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

• you probably do not want to spend much time updating a guide after every update -> write it more general
• avoid duplication: some wikis are extremely helpful, well maintained and translated in multiple languages: please don't repeat or copy-paste content for arch users at wiki.openstreetmap.org
•  KISS principle might be a help

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:
  • w:Requirements analysis
  • w:Use case and w:User story
• /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

• Daily update an OSM XML file - defined tools and scope (system, software); defined use cases; defined purpose; defined steps

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