RSW TWiki documentatie: Uitleg en regels voor gebruikers

We zijn een tijd geleden begonnen met het serieus in gebruik nemen van Twiki als pool voor documentatie en informatie uitwisseling binnen de RSW software ontwikkelgroepen en voor de waarnemers. Dit roept uiteraard vragen op als: wat kan ik in Twiki zetten, hoe ga ik er mee om. Dit document probeert de randvoorwaarden die ik stel voor documentatie in de RSW Twiki site helder te krijgen. Wanneer plaats je documentatie in Twiki, in wat voor vorm doe je dat, hoe gaan we om met Twiki webs, wat zijn de basisregels, etc.

TWiki is een specifieke implementatie van een Wiki documentatie systeem met vier belangrijke eigenschappen die het voor die functie geschikt maken:

1) Het is web-based, dus voor iedereen eenvoudig toegankelijk via een webbrowser

2) je hoeft geen HTML te kennen om in Twiki te kunnen werken. Twiki heeft een eigen syntax die de gebruiker in staat stelt eenvoudige lay-out zaken te coderen. Twiki vertaalt dit vervolgens naar HTML voor iedereen die een pagina oproept.

3) Twiki gebruikt een CVS versie beheer systeem om wijzgingen op pagina's bij te houden; daardoor is het altijd mogelijk de geschiedenis van een pagina te achterhalen, of wijzgingne ongedaan te maken.

4) In principe kan iedereen informatie toevoegen, veranderen, verplaatsen, weghalen, wat het bijzonder geschikt maakt voor een omgeving met verandernde omstandigheden en tevens laagdrempelig maakt voor gebruikers: het is je “eigen” documentatie, niet die van “iemand anders”.

Binnen een Twiki omgeving is er wat eigen jargon waarvan het handig is als je daarmee bekend bent:

Twiki Naam: Twiki gebruikt een aparte syntax voor namen die geassocieerd worden met Twiki-eigen gebieden (topics), gebruikers, etc. Dit zijn namen die tegen elkaar aan worden geschreven en minimaal twee hoofdletter bevatten. Voorbeelden zijn ArnoSchoenmakers, ProgDoc, JaVa, CPlusPlus, etc. Dit soort namen zijn dus altijd gereserveerd voor Twiki-eigen zaken, en kunnen door gebruikers van Twiki alleen gebruikt worden bij het maken van nieuwe topics, nieuwe gebruikersnamen, etc.

Twiki Web:

Een specifieke omgeving waarbinnen documentatie van een bepaalds onderwerp terug te plaatsen en terug te vinden is. Officieel geldt dat elk web een begrensd samenwerkingsgebied vormt (“an area of collaberation”). In onze setting kunnen we stellen dat een Twiki web een goed gedefinieerd informatiegebied mag zijn (bv. Python, TMS, Java, etc.). Dat betekent natuurlijk niet dat er geen kruisverbanden mogen zijn. Het maken van een nieuw Twike web is iets dat op Unix filesysteem niveau moet gebeuren, en daarvoor zal contact moeten worden gezocht met Arno Schoenmakers. Twiki webs worden aangeduid als Twiki.Main (Main web), Twiki.CNI (CNI web), etc.

Twiki Topics: Binnen een Twiki web zijn Topics gedefinieerd. Elke Twiki pagina heeft een uniek Topic. Topics kunnen eenvoudig worden aangemaakt door nieuwe pagina's te definieren. Zie hiervoor de Twiki handleiding (of vraag Arno Schoenmakers). Twiki topics kunnen ook weer subtopics hebben, en dit kan meerdere lagen diep zijn. Dit kan leiden tot constructies als Twiki.TMS (Topic TMS in het Main web), Twiki.TMS.ProgDoc

Twiki Users: Twiki Users zijn geregistreerde gebruikers van de Twiki omgeving. Iedereen kan Twiki pagina's bekijken (mits toegang tot het intranet), maar om pagina's te veranderen moet je je registreren in de TwikiRegistration. Je krijgt dan een TwikiNaam en je moet een TwikiPassword opgeven. Beiden moet je onthouden. Zodra je een pagina wilt veranderen moet je je TwikiName en TwikiPassword geven. Op deze manier is enige controle mogelijk op het veranderen van pagina's. Registratie doe je hier, een lijst van geregistreerde gebruikers vindt je hier.

Twiki Syntax en Twiki text: Dit is de specifieke Twiki taal die een gebruiker in staat stelt eenvoudige opmaak van pagina's te doen zonder HTML kennis. Een link naar een beknopte handleiding (TextFormattingRules) vindt je altijd onderaan je edit pagina (of zie hier).

Twiki Attachments: Op iedere Twiki pagina kun je files uploaden. Deze files komen dan in een zgn attachment lijst op de pagina, waar iedereen ze weer kan downloaden voor eigen gebruik. Deze files kunnen door iedereen ge-edit en weer teruggezet worden en bieden dus dezelfde mogelijkheden als Twiki pagina's zelf, behalve dat de inhoud niet direct zichtbaar en dus ook niet “zoekbaar” is. Dit is wel erg geschikt voor het uitwisselen van programma's, tools, grote bestanden in anere formaten dan Twiki text, etc.

Twiki indeling: De Twiki site heeft geen vaste indeling. Er is een verzameling Twiki webs (die we liefst zo klein mogelijkhouden), en daarbinnen navigeer je door de lijst met Twiki topics. De indeling is aan verandering onderhevig; het is relatief eenvoudig een topic te verplaatsen, te hernoemen, etc. Alle links naar dat topic worden dan ook automatisch aangepast, zodat het risico op dode links binnen de Twiki documentatie minimaal is.

Twiki links Binnen de Twiki omgeving kun je eenvoudig links aanbrengen door te refereren naar het Twiki Topic van de link. Gebruik NOOIT URLs om binnen Twiki door te verwijzen, dan verlies je de mogelijkheid dat bij het verplaatsen of hernoemen van de pagina waar je naar refereert alle verwijzingen ook vanzelf worden aangepast. Zie de TWiki.TextFormattingRules voor de juiste syntax.

Twiki search Twiki heeft een allerlei zoekmogelijkheid om informatie te zoeken in Twiki pagina's. Dit werkt natuurlijk niet voor attachments.

Het doel van onze Twiki site is enigszins afhankelijk van het beoogde publiek voor de verschillende delen van de site.

Voor de software ontwikkelaars is het doel als volgt te definieren:

- Software ontwikkelaars de mogelijkheid bieden informatie en tools uit te wisselen in een eigen webomgeving - Gebruikers documentatie van zelf-ontwikkelde of veel gebruikte software tools opzetten en in stand houden. - Procedures voor software ontwikkeling opzetten en in stand houden

Voor WSRT gebruikers (denk aan de waarnemers) is het doel als volgt te definieren:

- Procedures en geheugensteuntjes voor het waarneemgebeuren opzetten en in stand houden. - Beschrijvingen van veel gebruikte (software) tools beschikbaar maken en bij de tijd houden. Dit is ook een taak van ontwikkelaars voorzover zij tools maken die door waarnemers gebruikt moeten worden (user manuals!).

Hoewel Twiki floreert door de laagdrempeligheid en de mogelijkeden tot instantane wijzigingen, wil ik toch enkele regels voorstellen om het enigszins in goede banen te leiden.

- Twiki namen: Gebruik zoveel mogelijk een Twikinaam die lijkt op je eigen naam. Dus geen HarryPotter als je Jan Klaassen heet.

- Nieuwe webs: Deze worden alleen gemaakt door ArnoSchoenmakers; neem dus contact op met hem als je behoefte voelt aan een nieuwe web omgeving; Arno zal een leeg web klaarzetten.

- Nieuwe topics: Gebruik logische namen. begin een pagina altijd met een kleine beschrijving wat op de pagina te vinden is (paar regels, maximaal).

- Weggooien van pagina's of attachments: Na toestemming van ArnoSchoenmakers. Arno kan evt. besluiten tot het maken van een tijdelijke backup.

- Externe links: Dit is alles wat verwijst naar lokaties BUITEN de Twiki site (dus ook als het op dezelfde webserver zit). Altijd aangeven dat het een externe link betreft en mede delen dat deze mogelijk onbetrouwbaar is! Voeg dus toe: “(external link, may not be reliable)”.

- Software downloads: Geen links naar download sites; doe liever een download van het product en voeg de file toe als attachment aan de Twiki pagina; dan heeft iedereen ook toegang tot dezelfde versie van het product (wel melden of Linux/windows etc.).

- Ondertekening: Als je tekst op een pagina toevoegt of wijzigt, zet dan je eigen TwikiNaam en datum onderaan de pagina (verwijder reeds bestaande naam/datum). Het “edit” scherm biedt je onderaan alvast de juiste regel aan die je met copy and paste op de juiste plek kan zetten.

Opmerking: Dit is niet meer nodig. Je kunt nu alleen onder je eigen naam inloggen om dingen te veranderen en in de 'revision' information onder in het scherm is te zien wie de laatste wijzigingen heeft gemaakt…– NicoVermaas - 12 Jul 2005

- Probeer zoveel mogelijk documentatie toe te voegen als Twiki text; Alleen als dit veel werk is, of het oorspronkelijke document is in een “onhandig” formaat, kun je evt. besluiten het als een attachment op te nemen. Bedenk dat ook vanuit Microsoft Word, of vanuit elke andere editor/wordprocessor, met copy en paste standaard tekst is over te zetten naar Twiki. Tekst met veel ondersteunende figuren of tabellen kan beter als attachment worden opgenomen, evenals tekst in pdf formaat e.d. Bestaande HTML documentatie pagina's met voornamelijk geformatteerde tekst kunnen met een kleine inspanning worden toegevoegd als Twiki pagina met copy and paste, en wat editing achteraf voor de juiste lay-out, e.d. Laat dit je echter niet tegenhouden omdat de winst van de toegankelijkheid middels Twiki groot is! Bij twijfel, overleg met ArnoSchoenmakers.

- Houdt het relevant; bedenk dat het doel is om heldere informatie uitwisseling te genereren.

- De voertaal is zoveel mogelijk engels, maar ik heb geen problemen met nederlandstalige pagina's als men het gevoel heeft dat dat duidelijker of eenvoudiger is.

<hr>

ArnoSchoenmakers - 06 Apr 2005