Wiki:Sv:Technical guide

Den här sidan förklarar hur du bör skriva en teknisk guide i denna wiki. Oändliga FAQ-sidor slösar bort allas tid: svåra att skriva, svåra att uppdatera, svåra att läsa, svåra att uppdatera översättningar från, svåra att synkronisera, svåra att länka och svåra att uppdatera sidan utan att bryta alla andras länkar. Den här sidan ger alternativa tillvägagångssätt till tekniska guider i denna wiki.

Hur man skapar faktiskt användbart innehåll

Huvudartikel: Wiki guidelines

Guide dina användare

• per mål, per uppgift
  • Förklara i termer av den senaste versionen som stöds, testad och färdig att använda, flytta irrelevanta anteckningar till separata sidor
• per felsökningssymptom

Överväg underhåll

• du förmodligen inte vill lägga mycket tid på att uppdatera en guide efter varje uppdatering -> skriv det mer allmänt
• undvik dubbelarbete: vissa wikis är extremt hjälpsamma, väl underhållna och översatta till flera språk: vänligen upprepa eller kopiera och klistra inte in innehåll för archanvändare på wiki.openstreetmap.org
•  KISS princip kan vara till hjälp

Länk till andra sidor

• Att tillhandahålla dina källor hjälper även läsarna
• officiella dokument, inklusive en av de bästa i branschen
• Väl förklarade avsnitt "Se även" längst ner på varje sida. Vad härnäst? Vad mer ska jag veta?
• Categories hjälper till att gruppera sidor och hitta liknande

Rekommenderad struktur för undersidor

Rekommenderad läsning: Wiki_guidelines#Structure. Om sidorna blir för långa kanske du vill dela upp innehållet på flera sidor. Kom ihåg att vägleda dina läsare. Annars hittar de inte sidorna. Följande är ett gammalt förslag på ganska långa tekniska guider:

• /Installation - översikt över nödvändiga komponenter, miljöoberoende instruktioner
  • Installation on system X (Installation på system X) - samma som ovan, men mer fokus på miljöspecifikt, du kan varna användare med "Vänligen läs /Installation först" här
• /Use cases (Användningsfall) - "Varför och när någon inte vill använda den här guiden och programvaran?" "Betingelser?". Förklara programvara i termer av:
  • w:Requirements analysis (w:Kravanalys)
  • w:Use case och w:User story
• /Features (Funktioner) - (inte en teknisk guide!) liknande ovan, men mindre teknisk vy, slutanvändarinnehåll
• /Limitations (Begränsningar) - i tekniska termer: tekniska avvägningar, beslut under utveckling och så vidare
• /Troubleshooting (Felsökning) - aka "FAQ"-sida, försök att inte svälla den här sidan, dela upp innehåll per uppgift, per miljö och så vidare. Granska Category:Tool X igen och uppdatera ytterligare referenser och "Se även"-sektioner.
• /Benchmarks - kommer endast att vara relevant för IO tunga verktyg och uppgifter

Bra exempel

• Daglig uppdatering av en OSM XML-fil - definierade verktyg och omfattning (system, programvara); definierade användningsfall; definierat syfte; definierade steg

Relaterade kategorier

Kategori:Teknisk guide

allmän överkategori för ett slags guider (bör flyttas till underkategorier därav)

Kategori:Föråldrad teknisk guide

guider som behöver uppdateras

Kategori:Guide

guider eller handledningar, mestadels icke-tekniskt innehåll för kartläggare