Wiki:Technical guide
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
- 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:
- /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