Differences

This shows you the differences between two versions of the page.

--- main:rswtwikirules [2007/03/01 20:39] – tmsadmin
+++ main:rswtwikirules [2008/09/19 09:12] (current) – arnoschoenmakers
@@ Line 1: / Line 1: @@
-====== RSW TWiki documentatie: Uitleg en regels voor gebruikers ======
+====== Introduction to the WSRT Operations Wiki ======
-==== Intro: ====
+This page contains the introduction to the WSRT Operations Wiki and the guidelines to use it. Users must be familiar with the guidelines before adding or updating information in this Wiki.
-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.
+===== Wiki? What Wiki? =====
-==== Twiki documentatie systeem ====
+A Wiki is a place to share information among a group of people. Information is not created by itself; instead, people must create the information so other people can benefit from the shared knowledge. The other people can then use their own knowledge to update existing or add new information. A wiki is therefore a highly dynamic information exchange platform. That some information will be outdated is unavoidable; please inform the [[lofaradmin|administrator]] if you encounter outdated infomation, this helps us to keep the Wiki as up to date as we can.
-TWiki is een specifieke implementatie van een Wiki documentatie systeem met vier belangrijke eigenschappen die het voor die functie geschikt maken:
+===== WSRT Operations Wiki =====
+This Wiki exists to collect operations related information of the [[http://www.astron.nl/p/observing.htm|WSRT]]. It is maintained and used by Radio Observatory staff.
-) Het is web-based, dus voor iedereen eenvoudig toegankelijk via een webbrowser
+To navigate this wiki, you can choose one of the sections in the navigation window on the left, or do a 'search' query in the search box.
-) 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.
+All users are invited (even urged!) to add or update information in this Wiki. If you want to add new information, but have not yet decided or just don't know where it belongs, please enter the information in the [[waitingroom:start|waiting room]]. Your information can always be moved to a more appropriate place later. The most important thing is, is that the information then already has entered this Wiki, which makes it available to other users. All new contributions must be in English.
-) 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.
+When you enter this Wiki for the first time, or without logging in, you have only read access to the public information. The right to make modifications is granted when you have [[this>doku.php?do=register|registered for an account]].
-) 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".
+All questions and remarks can be send to the [[ro_wiki@astron.nl|administrator]].
-==== Twiki jargon: ====
-Binnen een Twiki omgeving is er wat eigen jargon waarvan het handig is als je daarmee bekend bent:
-//Twiki Naam://
+===== Using a Wiki =====
-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://
+Every Wiki has its own syntax for text markup. Something one just needs to get acquinted to... For this Wiki, a brief explanation can be found [[http://wiki.splitbrain.org/wiki:syntax#external|here]], or, when you open a edit page, through a link ('syntax') provided at the top of your screen. The edit page has some short-cut buttons that you can for markup, sectioning, creating links, creating lists, inserting an image or attaching a document. It even has spell-checking options.
-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 [[Main:ArnoSchoenmakers|Arno Schoenmakers]].
-Twiki webs worden aangeduid als [[start|Twiki.Main]] (Main web), [[CNI:start|Twiki.CNI]] (CNI web), etc.
-//Twiki Topics://
+===== Some guidelines =====
-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://
+There are some simple rules we impose to 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 [[TWiki.TWikiRegistration|hier]], een lijst van geregistreerde gebruikers vindt je [[Main:TWikiUsers|hier]].
+  * All information should be in English
+  * Large documents can be attached. We prefer attached documents to be in pdf-format so they are viewable and printable by most users.
+  * Images are preferred as either jpg, gif, svg or png, as these are supported by nearly all browsers.
-//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 [[TWiki:TextFormattingRules|hier]]).
-//Twiki Attachments://
+===== Preferred page layout =====
-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://
+We strive towards a more-or-less uniform presentation of information. We therefore like to see a uniform page layout and navigation style.
-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//
+Most of the pages will simply be pages that lay out the tree structure leading to the desired documentation; these pages contain mostly links to other pages, and thus I call these //link pages//. The preferred style for a link-page is given [[main:linkpagelayout|on this page]].
-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//
+A //document//-page, on the other hand, contain mostly useful information. Of course, it will also contain some links but its main goal is not re-direct the reader, but to inform the reader. These pages may be referenced from several other (link) pages. The preferred style for a document-page is givene [[main:documentpagelayout|on this page]].
-Twiki heeft een allerlei zoekmogelijkheid om informatie te zoeken in Twiki pagina's. Dit werkt natuurlijk niet voor attachments.
-==== TWiki inhoud: ====
-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!).
-==== RSW Twiki regels: ====
-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
+Detailed documantation (i.e. pages with lots of text) should be at the lowest level.

Trace:

Differences

Navigation

Search

Toolbox

QR Code