[[intern]]
 

Werkinstructie Dokuwiki

01. Algemeen

Deze instructie geeft uitleg over structuur en opzet van de helpdocumenten. Tevens worden een aantal afspraken genoemd die we hanteren om het geheel goed te kunnen beheren en zo veel mogelijk pagina's kunnen delen tussen de verschillende paraplu-onderdelen. Hieronder nog een paar opmerkingen m.b.t. help & ondersteuning:

  • Bugfixes/bekende fouten blijven in het update-programma. Er komt een nieuwe versie van het update-programma. Hierin kunnen de aanpassingen worden vastgelegd.
  • De beschrijvingen van externe koppelingen komen niet in dit help-systeem. Deze beschrijvingen blijven losse (Word)documenten die alleen op speciaal verzoek (via verkoop / offerte) worden verstrekt aan klanten.
  • Er is geen rekening houden van het lokaal hosten van de help door klanten. Het kan zijn dat dit in de toekomst wel mogelijk wordt gemaakt door relatieve verwijzingen vanuit de programma's.

Een volledig overzicht van de mogelijkheden binnen Dokuwiki vind je via: Engelstalige handleiding van Dokuwiki


02. Structuur

Er is per paraplu-onderdeel (Infogroen Software, I.S.P. Software en CleanWare) een aparte wiki geïnstalleerd op de Kameleonserver. Bepaalde pagina’s die voor elk onderdeel hetzelfde zijn, staan in een aparte “Algemene” wiki kunnen staan. Dit betreft bijvoorbeeld de hoofdmodule Relatie, maar ook Boekhouding en grote delen van Order. Van Calculatie kunnen een aantal pagina’s gedeeld worden tussen GROEN en CLEAN.

Elke Dokuwiki heeft in de root altijd de volgende pagina’s: start, inhoud, faq, beheer, werkboek en algemeen. Daarnaast staat er per hoofdmodule één pagina in de root. De pagina’s beheer en algemeen worden telkens vanuit de Dokuwiki algemeenhelp gesynchroniseerd. Hieronder de links naar de vier Dokuwiki's:


Help & ondersteuning: Algemeen

Help & ondersteuning: Groen

Help & ondersteuning: ISP

Help & ondersteuning: Clean


In dit schema zijn 4 Dokuwiki’s opgenomen. GROEN, CLEAN, I.S.P. en ALGEMEEN zijn de paraplu-onderdelen. Elk onderdeel heeft dus een eigen Dokuwiki. Onder de paraplu-delen staan de hoofd-modules. Daaronder de modules. Dit schema is ook de mappenstructuur van de Dokuwiki-pagina’s. Per module kunnen uiteraard nog vele onderliggende mappen worden aangemaakt.

Om zoveel mogelijk gebruik te maken van gedeelde teksten, worden pagina’s van dezelfde hoofd-modules gesynchroniseerd. Dat betekent bijvoorbeeld dat als binnen GROEN, een tekst wordt aangepast van CALCULATIE, de aanpassing ook wordt doorgezet (alleen lezen) in de hoofd-module CALCULATIE binnen CLEAN. De kleuren in het schema verklaren de brontekst. CLEAN heeft bijvoorbeeld voor de teksten van de hoofd-module ORDER, de bron vanuit de I.S.P.-dokuwiki. In het onderdeel ALGEMEEN staan de hoofd-modules RELATIE en BOEKHOUDING. Deze zijn algemeen en zullen via een script regelmatig naar de andere Dokuwiki’s gekopieerd worden.

De mappen voor media (afbeelingen, pdf's, etc.) worden door de beheerder ingesteld, omdat het niet mogelijk is om deze aan te maken of aan te passen via de web-interface. De mappenstructuur binnen de pagina's en media is alleen nodig om het geheel overzichtelijk te houden en het onderhoud te vergemakkelijken.


03. Synchroniseren

Via een PHP-script worden de Dokuwiki's bijgewerkt. Dit houdt in dat voor ongeveer 80 % de pagina's vanuit Algemeenhelp worden gekopieerd naar de 3 andere Dokuwiki's. De gekopieerde pagina's hebben de eigenschap alleen lezen. Hierdoor kunnen ze niet per ongeluk in de verkeerde Dokuwiki worden aangepast. Het gebruikte script is hier na te lezen. Het script wordt met PHP.exe uitgevoerd. Via Geplande taken binnen het besturingsprogramma op de server, wordt de synchronisatie-actie op gezette tijden herhaald.

Vanuit de bewerk-omgeving worden de Dokuwiki's telkens gekopieerd naar de locatie voor de eindgebruiker. Dat betekent dat de versies die worden bewerkt, niet direct zichtbaar zijn voor de klant. Elke nacht zullen de Dokuwiki's worden overgezet, zodat klanten wel steeds over een actuele versie beschikken van de documentatie. De pagina's zijn door de eindgebruiker niet aan te passen. De bestanden hebben namelijk de eigenschap alleen lezen Er zit ook geen inlogmogelijkheid in deze versie.


04. Pagina's toevoegen

Pagina's kunnen eenvoudig worden toegevoegd door in een bestaande pagina een interne link te maken met daarin in de naam van de nieuwe pagina. Door vervolgens de pagina op te slaan en de link aan te klikken, zal Dokuwiki aangeven dat de pagina niet bestaat en dat deze kan worden aangemaakt. Hieronder een aantal afspraken om het toevoegen van pagina's gestructureerd te laten verlopen.

  • Als er bijvoorbeeld voor de hoofdmodule Calculatie een pagina moet worden toegevoegd, moet in de nieuwe link wel de verwijzing in de mappenstructuur worden gehandhaafd. Dus bij verwijzingen naar nieuwe pagina's, letten op gewenste mapverwijzingen.
  • De naam van de pagina mag maar 1 woord bevatten en de naam moet zo kort mogelijk worden gehouden. Hierdoor kan de lengte van de URL's worden beperkt.
  • Elk onderdeel onder de hoofdmodule heeft een pagina en een mapje voor dieper liggende pagina's.
  • Over de lengte / grootte pagina’s is afgesproken dat deze niet te groot mogen worden. Houd ongeveer 4 pagina’s aan.
  • De automatische nummering in Dokuwiki vormt een probleem als er tussendoor media wordt ingevoegd. De nummering begint dan opnieuw na de invoeging. Dit heeft geen prioriteit. Er kan het beste gebruik worden gemaakt van de opsommingtekens. Handmatig nummeren kan natuurlijk ook.
  • Bij het aanmaken van titels in de pagina, wordt tot niveau 4 automatisch in de inhoudsopgave opgenomen. Eventueel is dit via de instellingen uit te breiden of juist in te perken.
  • Er is ingesteld (zie aanpassingen) dat er automatisch een link Naar boven wordt gecreëerd naar bij elke titel vanaf nivo 4. Dit is handig voor de gebruikers, waarbij de inhoudsopgave niet vast blijft staan bij scrollen. Hierdoor hoeft men telkens terug te scrollen. Als blijkt dat alle internet browsers (o.a. Firefox, Intenet Explorer 7) het vasthouden van de inhoudsopgave ondersteunen, kan deze functie er uit worden gehaald.

Zie voor alle mogelijkheden: Maak nieuwe pagina in Dokuwiki


05. Titels en tekst

De opmaak van de tekst en titels wordt voor het grootste deel bepaald door de stylesheet binnen de Dokuwiki en kan door de beheerder worden aangepast. Hiervoor is wel kennis van PHP nodig. De opmaak van de titels en inhoudsopgaven kan door een gebruiker niet worden aangepast en wordt dus volledig door de stylesheet bepaald. Dit maakt het werken binnen Dokuwiki eenvoudig en zorgt voor meer eenduidige opmaak (vooral bij meerdere tekstschrijvers). De opmaakmogelijkheden van de tekst zijn beperkt tot het gebruik van vet, cursief of onderstreept. Deze mogelijkheden kunnen wel gecombineerd worden. In het bewerk-gedeelte van de pagina kunnen teksten eenvoudig van de gewenste opmaak worden voorzien door de tekst te selecteren en het opmaak-icoontje uit de werkbalk te kiezen.

  • Teksten die voor de verschillende paraplu-onderdelen worden geschreven, moeten zoveel mogelijk algemeen blijven. Hierdoor wordt het mogelijk om zoveel mogelijk teksten onderling te delen. Let hier op, met name tijdens het geven van voorbeelden.
  • Gebruik bij het aanmaken van titels alleen de opmaakcodes H1 of H2 (zie knoppelbalk in het aanpassen-gedeelte) als titel aan het begin van de pagina. Hierdoor zal een horizontale lijn over de gehele breedte van de pagina onstaan. Het gebruik van meerdere horizontale lijnen in een pagina, zal het geheel drukker maken en hierdoor minder prettig om te lezen. Mogelijk is via de stylesheet te voorkomen dat met H2 de horizontale lijn automatisch wordt gegenereerd. Dit is nog in onderzoek. Hieronder een paar belangrijk aandachtspunten:
  • Het gebruik van H2 moet dus worden beperkt, omdat hiermee ook een horizontale lijn ontstaat.
  • Gebruik vervolgens H3 en hoger voor verdere uitsplitsing van de tekst.
  • Nummer de titels. Dus bijvoorbeeld 2. Orderverwerking als titelnaam. Nummer zelf door in onderliggende titels, zoals 2.1 Order invoeren en 2.2 Order bevestigen, etc.
  • Een extra witregel zoals onder deze regel is te forceren door 2 backslashes achter elkaar te zetten.


Verdere toelichting over het gebruik van titels binnen Dokuwiki kun je vinden via: Titels

Verdere toelichting over tekst binnen Dokuwiki kun je vinden via: Tekst

Het gebruik van tabellen is ook mogelijk binnen Dokuwiki, zie hiervoor: Tabellen


06. Afbeeldingen

images.jpg Afbeeldingen kunnen pagina's levendig maken en belangrijke punten verduidelijken. De meest gebruikte afbeeldingen zullen schermafdrukken van de software zijn, waarvan een handleiding is geschreven. Daarnaast zullen diverse mogelijkheden in de programma's een standaard icoontje hebben als snelfunctie.

Het uploaden van nieuwe bestanden wordt gedaan met de Media manager, die vanuit de werkbalk in het bewerk-gedeelte is te starten via . Gebruik het upload-scherm om een bestand te uploaden. Eventueel kan bij het uploaden van bestanden een aangepast naam worden meegegeven (zorg er wel voor dat de extensie klopt!). Na het invoegen in de pagina, kan de gewenste afmeting, positionering en link-methode worden ingesteld.

Standaard zorgt Dokuwiki ervoor dat na invoegen van een afbeelding, de afbeelding is gelinkt naar het origineel met eventuele meta-data. De tag-informatie is deels wijzigbaar. Er kan bijvoorbeeld een betere naam worden ingesteld bij de betreffende afbeelding. Hieronder een aantal aandachtspunten om de functie van afbeeldingen zo goed mogelijk te gebruiken.

  • De in te voegen afbeeldingen moeten in de juiste (hoofd)module-map worden ge-upload. In Dokuwiki heet een map Namespace. Zorg er daarom voor dat je voor het uploaden eerst de juiste map hebt aangeklikt, anders komt de afbeelding de root terecht. De namespaces van de media moeten synchroon lopen met de namespaces van de pagina's.
  • Om een subnaamspace (onderliggende map) aan te maken, laat je die naam voorafgaan bij de bestandsnaam”, gescheiden door een dubbele punt.
  • Bij afbeeldingen waarbij een link naar het origineel niet nodig is (bijvoorbeeld icoontjes of afbeeldingen op ware grootte), dan in de link naar de afbeelding de tekst nolink achter de bestandsnaam typen (uiteraard in het wijzig-gedeelte van de pagina's).
  • Afbeeldingen zoveel mogelijk in JPEG-formaat gebruiken.
  • Afbeeldingen mogen maximaal 100 Kb zijn. Dit voorkomt dat een pagina enige tijd staat te laden (downloaden) bij de gebruiker om de afbeeldingen weer te geven.
  • Afhankelijk van de grootte, moeten de afbeeldingen na het invoegen in de pagina worden verschaald. Het maximum aantal pixels is vastgesteld op 300 (dit slaat op de breedte-maat van de afbeelding). Kleinere afbeeldingen mogen natuurlijk ook.
  • Elke afbeelding dient in de juiste media-map te worden geplaatst. De naam van de afbeelding is de naam van module en het volgnummer. Dus bijvoorbeeld voorcalculatie_01.jpg zal in de media-map calculatie\voorcalculatie\ worden ingevoegd.
  • Als de afbeelding afwijkend moet zijn voor de andere paraplu-wiki's, dan in gelijk de afwijkende afbeeldingen ook maken en in de betreffende Dokuwiki(s) plaatsen. Direct controleren of de nieuw ingevoegde afbeeldingen in alle Dokuwiki's goed worden weergegeveven. De naamsverwijzing van afbeeldingen voor isp, groen en clean dienen dus gelijk te zijn. Een schermafdruk van Order kan bijvoorbeeld ORDER011.jpg zijn genoemd. Door deze naam in de verschillende Dokuwiki’s gelijk te houden, kunnen ze andere afbeelding oproepen met dezelfde tekst.
  • Voor de positionering van de schermafdrukken is gekozen om de afbeelding in het midden tussen de tekst te plaatsen. De afbeeldingen wordt automatisch horizontaal gecentreerd door een spatie voor en achter de link te plaatsen.

  • Kleinere afbeeldingen, zoals icoontjes mogen wel door de tekst heen of vooraan de regel worden ingesteld.
  • Bij het invoegen van afbeeldingen, alleen het aantal breedte-pixel opgeven en geen directe link. Hierdoor kan de gebruiker gemakkelijk via de terug-link naar de vorige pagina gaan. Nadeel is dat er metadata-info wordt weergegeven. Theo gaat bekijken of dit weg te halen is.


Verdere toelichting over afbeelingen van Dokuwiki kun je vinden via: Uitleg over het gebruik van afbeeldingen

Ook via: Afbeeldingen en media


07. Video bestanden

Instructie-filmpjes worden gemaakt met Camtasia Studio 6.0. De instructie-filmpjes willen we gebruiken in de online help en E-learning. Camtasia Studio is een programma om de handelingen in het scherm op te nemen en daar video-bestanden van te maken. Hieronder een aantal aandachtpunten voor het maken van video-bestanden:

  • Video-bestanden in het formaat ‘swf’ kunnen door Dokuwiki worden afgespeeld. Het standaardformaat binnen Dokuwiki is 427×320. Het formaat is aan te passen.
  • De video-bestanden kunnen dus in de media-map van de betreffende Dokuwiki worden geplaatst via de media-manager van Dokuwiki.
  • Het is niet mogelijk om de video-weergave aan te passen of te maximaliseren.
  • Alternatief is linken naar Youtube.com (of Screencast.com van Camtasia).
  • De video’s op tuinkalender.nl zijn gemaakt met Camtasia Studio. Deze demo-filpjes hebben het formaat 580×447.
  • Advies is om het formaat 580×435 te gebruiken.
  • Voor de zichtbaarheid kan de muisaanwijzer beter “groot” worden ingesteld. De bekijker kan dan beter volgen wat er wordt aangeklikt. (via configuratie-scherm in te stellen)
  • Door het aantal frames (per seconde) te verlagen, wordt het bestand kleiner en daarmee beter af te spelen in een browser. Standaard ligt de snelheid (voor web) op 15 frames.
  • Opties als ‘maximaliseren’ en ‘info’ uitschakelen, omdat ze niet werken binnen Dokuwiki.
  • Camtasia zoomt automatisch in op de onderdelen die worden aangeklikt in het scherm. De zoom-momenten zijn achteraf aan te passen.
  • Audio is ook mogelijk. Hiervoor zijn 3 sporen beschikbaar in het programma, waarvan 2 separaat van de video te regelen. (denk aan geluidsterkte, fade in/out, overgangen)
  • Er zijn t.b.v. E-learning mogelijkheden voor het inbouwen van vragen. Deze worden via SCORM verwerkt. SCORM is een set van afspraken, hoe e-learning moet worden opgesteld.
  • Minimum systeemeisen Camtasia: 1.0 GHz processor, 500 MB RAM
  • Uploaden Dokuwiki is beperkt tot 2Mb per bestand. Hierdoor zal het soms nodig zijn om de bestanden via ftp over te zetten in de juiste media-map.

08. Overige bestanden

Naast afbeeldingen, kunnen ook andere bestandstypen worden gelinkt van Dokuwiki-pagina's. Afbeeldingen en Flash media worden direct weergegeveven op de pagina, maar andere bestanden (zoals PDF documenten) worden alleen gelinkt naar het document. Maak bij voorkeur gebruik van het pdf-formaat. Een pdf-Reader is gratis van internet te halen en kan daarmee door elke gebruiker worden gelezen.

In het bewerk-gedeelte van de pagina's kan door het klikken op icoontje van afbeeldingen invoegen, het scherm voor bestandsselectie worden geopend. Hiermee zijn dus naast afbeeldingen, ook andere bestanden te uploaden en vervolgens als link in de pagina in te voegen.

  • De in te voegen bestanden moeten in de juiste (hoofd)module-map worden ge-upload. In Dokuwiki heet een map Namespace. Zorg er daarom voor dat je voor het uploaden eerst de juiste map hebt aangeklikt, anders komt de afbeelding de root terecht. De namespaces van de media moeten synchroon lopen met de namespaces van de pagina's.
  • Om een subnaamspace (onderliggende map) aan te maken, laat je die naam voorafgaan bij de bestandsnaam”, gescheiden door een dubbele punt.
  • Bij afbeeldingen waarbij een link naar het origineel niet nodig is (bijvoorbeeld icoontjes of afbeeldingen op ware grootte), dan in de link naar de afbeelding de tekst nolink achter de bestandsnaam typen (uiteraard in het wijzig-gedeelte van de pagina's).
  • Elke bestand dient in de juiste media-submap te worden geplaatst. Dus bijvoorbeeld schema_opslagen.pdf zal in de media-map calculatie\voorcalculatie\ worden ingevoegd.
  • Als het bestand afwijkend moet zijn voor de andere paraplu-wiki's, dan gelijk deze bestanden ook maken en in de betreffende Dokuwiki(s) plaatsen. De naamsverwijzing van de bestanden voor isp, groen en clean dienen dus gelijk te zijn.


Beschikbare bestandsformaten die binnen de Mediamanager kunnen worden ge-upload: Bestandsformaten

Via de volgende link wordt het omgaan met afbeeldingen en andere bestanden uitgelegd: Afbeeldingen en media


09. Beveiliging

Beveiliging Het benaderen van de helppagina’s wordt beveiligd met een algemeen wachtwoord. Dit wordt geregeld via de Apache webserver. Indien de help vanuit de applicatie wordt gestart, is de gebruiker wel direct ingelogd. Jaarlijks wordt het wachtwoord worden aangepast, om ongewenst gebruik te voorkomen. Klanten die bijvoorbeeld alleen de hoofdmodule Calculatie hebben, kunnen wel de help van andere (hoofd)modules lezen.

T.b.v. synchronisatie mogen van bepaalde pagina’s alleen de bronpagina’s worden gewijzigd. Via een script worden de gewijzigde pagina’s regelmatig pagina’s in andere Dokuwiki’s overschrijven. De overschreven pagina’s zullen de eigenschap ‘alleen lezen’ moeten hebben, om fouten te voorkomen.

Binnen de Dokuwiki's is Mark de beheerder. Acties als gebruikers aanmaken en rechten toekennen verlopen via de beheerder. Op dit moment zijn Theo, Michel, Koen, Karin en Erik als gebruiker ingesteld met schrijfrechten.

De beheerder zal in de Dokuwiki: algemeenhelp gebruikers aanmaken die alleen pagina’s mogen aanpassen en niet aanmaken. In GROEN/ISP/CLEAN gebruikers aanmaken die vanaf een bepaald niveau in de mappen wel pagina’s mogen aanmaken en aanpassen. Hoger liggende pagina’s die vanuit ALGEMEEN komen, worden beveiligd met de eigenschap ‘alleen lezen’.


10. Aanpassingen Dokuwiki

menwork.jpg Er zijn een aantal aanpassingen gedaan in php-bestanden van de Dokuwiki's en ook zijn er stylesheets aangepast. Daarnaast zijn een aantal instellingen geactiveerd in het beheergedeelte van de Dokuwiki's. Hieronder zijn de aanpassingen gedocumenteerd.

  • De footerbuttons zijn weggehaald door het betreffende script te verwijderen uit de stylesheet.
  • Om de automatisch inhoudsopgave vast te zetten(IE7 en firefox) is dit aangepast in de stylesheet op lib/tpl/default/design.css.
  • Automatisch link Terug naar boven onder elke titel vanaf niveau 4, is ingesteld via deze beschrijving.
  • Het herschrijven van de URL is in de Apache webserver ingesteld voor zo kort en duidelijk mogelijke adressen via deze beschrijving.
 
intern.txt · Laatst gewijzigd: 2009/10/16 12:33 (Externe bewerking)