1. Documentatie in Brocade

1.1. Inleiding

In het begin van de jaren '90 nam de bibliotheek van de Universiteit Antwerpen deel aan een Europees project (CEC Project: LIB-HYPERLIB/3-1015) dat tot doel had om hypertextstructuren te gebruiken in bibliotheekpraktijken. Documentatie van procedures was een van die aandachtspunten. Tijdens de uitvoering van het project veranderde de informatiewereld dramatisch: het World Wide Web werd geboren. HyperLib - dat was de naam van dit bibliotheekproject - kwam net op tijd om hier op in te spelen: niet alleen een documentatieplatform, maar ook het plaatsen op het web van de bibliotheekcatalogus en de academische bibliografie werd gerealiseerd en met hypertext als voornaamste ontsluitingstechniek.

De praktische verwezenlijkingen - de software zeg maar - waren natuurlijk belangrijk, maar toch zijn het andere aspecten van het project die een blijvende impact hadden: diverse gebruikersonderzoeken leerden de ontwikkelaars de ware ziel van hypertext te doorgronden. Ook de tijd die werd vrijgemaakt om na te denken over zowel de goede als de minder geslaagde aspecten van de uitgewerkte oplossingen, is gewoonweg onbetaalbaar.

Heel wat van de ontwerpbeslissingen in het nieuwe documentatieplatform voor Brocade vinden hun oorsprong in de ervaringen opgedaan in die tijd.

Deze ervaringen vormen het belangrijkste onderdeel van deze tekst. Echter, om deze goed te kunnen begrijpen is het belangrijk de technologische componenten even onder de loupe te nemen. Dit biedt meteen de gelegenheid om de impact van opensource software toe te lichten.

1.2. Technologische componenten

1.2.1. Markup structuren

Documentatie wordt steeds beschreven met behulp van een Markup taal. Dit komt omdat documentatie meer is dan woorden. Deze woorden komen pas tot hun recht indien daar structuur wordt aan gekoppeld: woorden worden titels, lijsten, hyperlinks, tabellen. Markup talen voorzien in allerlei instrumenten om tekst en structuur te koppelen.

In het HyperLib project was markup gebaseerd op een experimentele HTML versie. DocBook is een andere en veel gebruikte markup taal (ook SGML en XML gebaseerd) waarmee binnen Brocade werd geëxperimenteerd.

Ook in de open source wereld worden een aantal markup talen gepromoot. Voorbeelden daarvan zijn onder meer asciidoc, reST en Markdown.

Binnen Brocade worden reST en Markdown gebruikt.

Waarom twee Markup systemen? Ogenschijnlijk hebben deze twee systemen veel gemeenschappelijk, maar toch is hun toepassing (alvast binnen Brocade) heel erg verschillend. Markdown wordt consistent gebruikt binnen de Brocade software zelf: hulpboodschappen voor de gebruiker, annotaties bij bijvoorbeeld archief- en object beschrijvingen. Het zijn veelal kortere teksten die toch wel enige markup kunnen gebruiken (beklemtonen van bepaalde onderdelen, opsommingen, hyperlinks).

reST daarentegen is veeleer gericht naar grotere teksteenheden zoals de documentatie van de catalografische principes, richtlijnen voor de leeszaalmedewerkers.

Ook de auteurs zijn verschillend: bij Markdown is er nauwelijks opleiding nodig en van elkeen die bijvoorbeeld een archiefbeschrijving aanmaakt kan worden verwacht dat ze de diverse annotaties, de historiek van het archief e.d. in een eenvoudige Markdown kunnen gieten.

Van auteurs die documentatie schrijven, wordt meer verwacht: ze moeten de plaats kennen van deze documentatie binnen het geheel. reST en Sphinx bieden allerlei faciliteiten om dit tot zijn recht te laten komen.

De twee markup systemen hebben gemeenschappelijk dat ze gebaseerd zijn op vlakke tekst. Dit betekent dat er onmiddellijk een pleiade van instrumenten voorhanden is om de documentatie aan te maken en te beheren: editors (gaande van een programmer's editor tot MS Word), versie controle systemen, indexeersystemen.

Het meest tot de verbeelding spreekt de (tekst)editor. Hoewel dit helemaal geen verplichting is, wordt binnen Brocade vooral Textadept gebruikt. Dit is een opensource instrument. De bibliotheek van de Universiteit Antwerpen sponsorde dit project om allerlei hulpmiddelen te maken om precies het documentatieproces te versnellen. Deze hulpmiddelen zijn (vanzelfsprekend) ook opensource.

1.2.2. Sphinx

Sphinx is een opensource software die werd ontwikkeld om grote software pakketten te documenteren. Het werd voor het eerst toegepast op Python, een programmeertaal die wereldwijd door belangrijke organisaties wordt gebruikt.

Sphinx evolueerde tot een allround documentatiesysteem waarmee niet alleen webpagina's kunnen worden geproduceerd, maar evengoed PDF documenten, e-books (in ePub), Windows Help documentatie en zomeer.

Een groot deel van dit succes was te danken aan de programeerbaarheid van het systeem: de gebruikte markup taal (reST), templates (Jinja2), plug-ins laten toe om het documentatiesysteem naar de hand te zetten. In dit opzicht zijn templates echt belangrijk: deze laten toe om het productieproces te versnellen, homogeen te maken en zelfs dynamiek te geven. Dit dynamisch maken, betekent dat een gedeelte van de documentatie wordt gegenereerd op basis van gegevens die in andere omgevingen zit. Een voorbeeld maakt dit duidelijk: stel dat men een bepaalde functionaliteit van Brocade wil documenteren. Het ligt dan voor de hand om de lezer te tonen waar hij deze functionaliteit terug kan vinden in de menustructuur van Brocade. De documenteerder hoeft enkel de interne code van de applicatie te vermelden: het dynamisch systeem vormt deze code om naar een passende, gebruiksvriendelijke navigatie naar de applicatie.

Ook hier sponsorde de bibliotheek van de UA een belangrijk opensource project om het template systeem van Sphinx compatibel te maken met Textadept.

1.2.3. WebDAV

Documentatie moet niet alleen worden geschreven en ontplooid, maar het moet ook professioneel worden beheerd. Binnen Brocade begint het beheer van deze documentatie met de opslag. De technologie die hiervoor wordt gebruikt, is het WebDAV protocol. Dit uit zich als een open source add-on voor de Apache webservers waarop Brocade functioneert. Voor de auteur van documentatie manifesteert WebDAV zich als een eenvoudige schijf op zijn werkstation waarop hij zijn documenten kwijt kan. Onderhuids worden de documenten echter getransporteerd naar de webserver. Daartoe wordt op de werkstations van het bibliotheekpersoneel een commerciële software geïnstalleerd. Dit is enkel nodig op Windows werkstations: Mac en Ubuntu zijn 'uit het doosje' voorzien van deze software.

Eens de documentatie op de webserver (via WebDAV) staat, starten er een heleboel procedures om deze documentatie te beheren:

  • allerlei backup faciliteiten: behalve op de Brocade server zelf, worden de bestanden nog op twee backupservers weggeschreven.

  • versie controle: het is voor de auteurs steeds mogelijk om naar een vorige versie van de documentatie terug te keren.

  • productie van de gebruikersdocumentatie: hoewel heel goed leesbaar, is de reST toch niet echt geschikt voor het doelpubliek. Iedere dag wordt de documentatie gepubliceerd in diverse vormen (HTML, PDF, …)

Het is belangrijk om te beklemtonen dat de auteurs zich van deze procedures helemaal niets hoeven aan te trekken: zij gebruiken enkel hun tekstverwerker.

1.2.4. Lucene

De datastructuren uit een Brocade bibliotheek worden doorzoekbaar gemaakt door middel van de Lucene opensource.

Sphinx komt met een eigen zoekstructuur. Toch is de Lucene aanpak beter: wildcards, proximity search, facetten zijn zo van die dingen die de bibliotheekwereld heeft leren appreciëren en die niet standaard in Sphinx aanwezig zijn.

Op termijn zal de bibliotheekaanpak met Lucene ook worden verwezenlijkt in het documentatieproces: de plug-in interface van Sphinx maakt dit mogelijk.

1.3. Ervaringsgegevens

Uit het HyperLib project heeft het automatiseringsteam van de UA-bibliotheek heel wat ervaringen opgedaan. We sommen de belangrijkste hiervan op en merk meteen hoe de gekozen technologieën hierop inspelen.

1.3.1. De auteur is het meest kostbare goed in de documentatieketting

Mensen die documentatie schrijven zijn experten. Door hun persoonlijkheid, hun ervaring en hun plaats in de organisatie zijn ze in staat om procedures en concepten te vatten in woorden die begrijpbaar zijn voor hun doelpubliek. Auteurs kennen zowel:

  • de materie

  • hun publiek

  • de organisatie

  • de sector

Kennis van deze vier aspecten is nodig om geschikte documentatie te schrijven. Het belang van de sector moet toch even apart worden beklemtoond: documentatie voor bibliotheken en archieven wordt geschreven en gebruikt in een achtergrond waar het woord en taal belangrijk zijn. Documentatie mag, ook in dit opzicht, niet achterblijven.

Het is duidelijk dat auteurs een speciale rol opeisen in hun organisatie. Het zijn drukbevraagde mensen en het is weinig waarschijnlijk dat documentatie schrijven hun enige taak is.

Dit betekent dat het documentatieplatform zelf een minimum aan hindernissen mag plaatsen en zo goed mogelijk moet worden ingepast in het instrumentarium dat de auteur dagelijks hanteert op zijn vertrouwde werkplek.

Alleen ..., "vertrouwde werkplek" is heel wat minder conventioneel als het misschien wel klinkt. Uit diverse anekdotes blijkt dat documentatie wordt geschreven op de meest verscheiden plaatsen en momenten: op de trein van en naar huis, in het Internetcafe, in de wachtzaal, tijdens een minder interessante lezing, tijdens leeszaaldiensten.

Op deze verscheidenheid moet het documentatieplatform weten in te spelen.

In de HyperLib periode werd documentatie geschreven in een SGML (Standardised General Markup Language), ietwat te vergelijken met XML. Als schrijfinstrument werd Emacs gebruikt. Emacs is een legendarische programmer's editor en de ontwikkelaars waren dan ook stomverbaasd dat de auteurs één na een afhaakten toen dit onding op hun werkstation verscheen.

Door te kiezen voor reST en Markdown als Markup talen, kan de auteur kiezen welk instrument hij gebruikt. Behalve het hoger genoemde Textadept wordt ook Notepad++ en Komodo Edit gebruikt. Dit zijn allemaal opensource producten die volledig vrij mogen worden verspreid en ingezet.

Markdown en reST hebben eigenschappen die heel goed overkomen bij onze auteurs:

  • Deze markup is minimalistisch, een groot verschil met de overdaad aan tags uit de SGML periode.

  • De documentatie is ook heel goed leesbaar zonder verwerking.

  • Het leerproces is minimaal. Dit leidt tot merkwaardige toepassingen: je ziet de markup verschijnen in korte notities, bij het uitzenden van e-mails, voor het invullen van een issue-tracker.

De keuze voor WebDAV maakt dan weer dat de auteur niet langer gebonden is aan een fysieke werkplaats: de teksten en bijhorend illustratiemateriaal zijn steeds beschikbaar over het Web heen.

Het beheer van het materiaal (backup, versie controle, toegangsrechten) wordt door de bibliotheeksoftware beheerd en is voor de auteur "business as usual".

1.3.2. Documentatie moet mooi zijn

Een paar jaar geleden toonde National Geographic uitzendingen waarin Lockheed en Boeing in strijd gingen om de Joint Strike Fighter bestelling van de Amerikaanse strijdmachten binnen te halen. De inzet was extreem hoog: alleen al in de US zouden er al 2443 toestellen ter waarde van 1,45 triljoen dollar (u leest dit goed: 5 maal de staatsschuld van België) worden geleverd.

Het leverde fascinerende televisiebeelden op: wat je van oorlogstuigen ook mag denken, de twee toestellen waren/zijn staaltjes van menselijk vernuft. Het hoogtepunt van de documentaire was het moment dat de journalist aan de drie sterren generaal vroeg welk element de doorslag gaf bij de keuze. De generaal keek de reporter aan en even verscheen, over het verweerde gelaat van de veteraan heen, het gezicht van het jongetje dat hij ooit was en hij antwoordde: _Wel, we hebben simpelweg het mooiste toestel gekozen!_

Deze overwegingen gaan zeker op voor documentatie. Ervaringen uit het HyperLib project en experimenten met DocBook tonen ten overvloede aan dat auteurs zich te kort gedaan voelen als ze zien tot wat hun inspanningen maar leiden.

Sphinx maakt komaf met vlakke documentatie. Door een strikte splitsing van vorm en inhoud kan de vormgeving gemakkelijk worden aangepast en bijvoorbeeld worden ingebed in de huisstijl van de organisatie.

Een belangrijke rol wordt hierbij gespeeld door het opensource karakter: designers spelen daar op in om "themes" te ontwikkelen die dan ook vrij ter beschikking komen.

Deze splitsing tussen vorm en stijl maakt het ook mogelijk om documentatie, geschreven door verschillende auteurs over verschillende onderwerpen, toch als een harmonisch geheel te bundelen.

1.3.3. Documentatie moet worden hergebruikt

Alle auteurs zijn het er over eens: het twee maal schrijven van essentieel dezelfde documentatie, gewoonweg omdat het instrumentarium niet goed genoeg is uitgebouwd, is een onding. Het onderhoud van deze dubbele informatie is dat des te meer. Uiteindelijk hebben we precies daarom, in de bibliotheekwereld, authority controle uitgevonden.

Dit betekent dat de auteur bij het schrijven van de documentatie moet kunnen verwijzen naar andere documentatie concepten die dan in de uiteindelijke tekst op automatische wijze worden ingelast door het productieproces. Deze 'andere documentatie' kan ook dynamisch van aard zijn, met andere woorden, documentatie die wordt gegenereerd. Een goed voorbeeld hiervan zijn statistische gegevens (bezoekersaantallen, aantal volumes in de bibliotheek) die hun plaats vinden in de documentatie maar die, over de tijd heen, evolueren.

Dit evoluerend karakter brengt met zich mee dat de documentatie zoals ze zich presenteert naar de gebruiker toe, ook voortdurend moet worden aangepast. Een bibliotheeksysteem excelleert in het bijhouden van metadata en deze metadata is ook van toepassing op documentatie. Deze kan dan worden aangewend om de gebruikerspresentatie op te frissen.

Brocade gaat reeds heel ver in het hergebruik van documentatie, maar toch is hier nog ruimschoots plaats voor nieuwe ideeën en toepassingen.

1.3.4. Documentatie moet binnen handbereik zijn

Wat het bibliotheekpersoneel betreft, zijn er twee vormen van documentatie:

  • enerzijds is er de documentatie die vertelt hoe hij zijn instrumentarium (lees: bibliotheekbeheerssysteem) moet gebruiken

  • anderzijds zijn er de richtlijnen van zijn organisatie (hoe hij bepaalde metadata moet verwerken, hoe hij moet omgaan met bepaalde lezers, ...)

In lastenboeken wordt steeds de klemtoon gelegd op de eerste soort documentatie. De ervaring leert echter dat een doorwinterd biblothecaris deze documentatie nauwelijks nodig heeft. Men zou zelfs kunnen stellen dat dit soort documentatie dient om het falen van de interface van het bibliotheeksysteem te verdoezelen.

De tweede vorm van documentatie is veel belangrijker en dit is zeker zo in de snel veranderende wereld van de informatiebedrijven. Bibliotheken en archieven maken ook veelvuldig gebruik van tijdelijk personeel, jobstudenten, vrijwilligers. Doorstroming van interne informatie laat in deze groep wel wat te wensen over.

Met Sphinx en Brocade kunnen aan de beide documentatievormen worden voldaan: de documentatie over functionaliteit wordt getoond via het context menu (rechter muisklik) in de browser en de bedrijfsprocedures zijn dan weer toegankelijk door middel van een icoon in Brocade.

De auteur en het bibliotheeksysteem zorgen er voor dat deze documentatie contextgevoelig is: er is ingebedde meta-informatie die deep-linking mogelijk maakt.

1.4. Documentatie structuren

De documentatie structuren binnen Brocade worden bepaald door een mengeling van eisen qua functionaliteit en autonomie.

Wat functionaliteit betreft zijn de volgende aspecten bepalend:

  • de opzoekbaarheid

  • het linking mechanisme

  • de hiërarchie (navigatie mogelijkheden)

  • vormgeving

Autonomie staat voor de compleetheid van de documentatie:

  • linken kunnen worden gevolgd

  • zoeken leidt tot de gewenste pagina's: niet teveel, niet te weinig

Onderaan de ladder der documentatie structuren staan de documentatie bestanden (reST bestanden).

Deze worden thematisch verzameld tot documentatie eenheden. Documentatie eenheden zijn terug te vinden op productieservers onder een welgekend webadres. Dit adres kan worden opgenomen in menu-ingangen van zowel Brocade als van de Desktops. Het is ook heel goed mogelijk (en zelfs waarschijnlijk) dat een zelfde reST document terecht komt bij meerdere documentatie eenheden (zie verder). Een documentatie eenheid komt overeen met een Sphinx document: de samenstelling ervan wordt essentieel gestuurd door een index.rst bestand. Een documentatie eenheid heeft ook een uniforme design.

Documentatie eenheden worden dan weer verzameld in documentatiegroepen. Deze groepen staan voor de complete documentatie binnen een organisatie. De documentatie eenheden binnen zo'n groep mogen enkel links bevatten binnen zichzelf of naar andere documentatie eenheden binnen dezelfde groep. Het indexeer mechanisme moet werken binnen een groep.

Hoe kan de linking binnen een documentatiegroep sluitend worden gemaakt ?

Dit kan enkel door een goede samenstelling van de documentatie eenheden. Er komen 2 soorten eenheden in aanmerking om deel uit te maken van een gegeven documentatiegroep:

  • documentatie eenheden aangemaakt door de authoriteit achter de documentatiegroep

  • documentatie eenheden die Anet aanmaakt met precies als doelstelling om te worden gebruikt door de Anet partners. Dit houdt ondermeer de functionele beschrijving van de Brocade software in, maar evengoed de documentatie die wordt aangemaakt ten behoeve van het catalografisch regelwerk. Anet behandelt de eerste vorm van documentatie net zoals software: oplossen van bugfixes, updating, verdere uitwerking. Meer in het bijzonder: Anet onderhoudt de anchor punten in deze documenten. In de zeldzame gevallen dat anchor punten verdwijnen of veranderen, moeten de authoriteiten achter de documentatiegroepen op de hoogte worden gebracht.

De vormgeving van de documentatie eenheden is belangrijk: het is zaak ervoor te zorgen dat binnen een zelfde groep alle eenheden hetzelfde Sphinx thema voeren. Worden documenten uit twee verschillende groepen (met verschillende layout) gelinkt, dan zal bij het volgen van de link ook duidelijk worden dat de layout verandert.

Note

Een hiërarchie met 3 niveau's (groepen, eenheden, bestanden) biedt grote voordelen:

  • verdubbeling in raadpleging is mogelijk zonder de documentatie zelf te verdubbelen

  • herstructureren van de documentie kan zonder de bestanden te raken: de gekozen documentatiestructuur biedt het niet te onderschatten voordeel dat de auteur zich enkel moet richten op zijn bestanden. De uiteindelijke structuur kan achteraf worden opgezet, aangepast, veranderd. Met andere woorden: de structuur kan worden beheerd.

  • contextgevoelige help (zowel naar onderwerp als lokatie) is mogelijk en centraal beheersbaar

  • linking tussen documenten is eenvoudig en onafhankelijk van de fysieke plaatsing op de webserver

  • volgbare linken kunnen worden gegarandeerd

  • layout is vervangbaar

Een (fictief) voorbeeld om de structuur te verduidelijken:

  • Documentatiegroep ua

    • Documentatie eenheid lezerdiensten

      • bibliotheekreglement.rst

      • takenpersoneel.rst

      • lokaties.rst

      • opstellingmaterialen.rst

    • Documentatie eenheid catalografie

      • uatijdschriften.rst

      • uaoudedrukken.rst

      • antilope.rst

      • uaonderwerpsontsluiting.rst

      • uaplaatskenmerken.rst

    • Documentatie eenheid historischecollecties

      • beheersaspecten.rst

      • leeszaaldienst.rst

      • reglement.rst

      • digitalisering.rst

  • Documentatiegroep anet

    • Documentatie eenheid catalografie

      • authoritycontrole.rst

      • regelwerk.rst

      • aat.rst

    • Documentatie eenheid impala

      • afspraken.rst

      • clearinghouse.rst

      • bpost.rst

  • Documentatiegroep brocade

    • Documentatie eenheid systeem

      • installatiebrocade.rst

      • backup.rst

    • Documentatie eenheid releases

      • release390.rst

      • release400.rst

      • release410.rst

    • Documentatie eenheid software

      • developer.rst

      • toolsworkstation.rst

      • issuetracker.rst

      • m.rst

      • mparser.rst

      • meta.rst

    • Documentatie eenheid archief

      • setup.rst

      • functional.rst

      • meta.rst

1.5. Ontsluiting van documentatie

De ontsluiting van documentatie gebeurt in de eerste plaats op het niveau van de documentatie eenheid: het is precies hier dat een verzekerde ingang mogelijk wordt. De documentatie eenheid wordt gekenmerkt door 2 identifiers:

  • de eerste identifier staat voor de documentatiegroep en is van de gedaante [a-z][a-z0-9]* (M.a.w. het moet beginnen met een kleine letter en mag verder enkel uit kleine letters en cijfers bestaan). Een voorbeeld hiervan is ua. Er zijn twee namen gereserveerd: brocade en anet.

  • de tweede identifier staat dan voor de eenheid binnen deze groep. Ook deze identifier is van de gedaante [a-z][a-z0-9]*. Een voorbeeld hiervan is lezerdiensten.

Is de DNS van de productiemachine bij voorbeeld anet.uantwerpen.be, dan kan de documentatie van het zojuist vermelde voorbeeld worden gevonden op het webadres: https://anet.uantwerpen.be/doc/ua/lezerdiensten. Naargelang de specificaties is er ook een PDF beschikbaar op de link https://anet.uantwerpen.be/doc/ua/lezerdiensten/pdf of een ePUB formaat op de link https://anet.uantwerpen.be/doc/ua/lezerdiensten/epub.

1.6. Brocade documentatie

De documentatie wordt aangemaakt en onderhouden door het Anet team. Het betreft hier documentatie die hoort bij de Brocade software.

  • documentatie die beschrijft hoe de Brocade software functioneert

  • documentatie die de installatie van de Brocade software beschrijft

  • documentatie die het vervaardigen van Brocade software beschrijft

  • documentatie het release beheer beschrijft

  • BVVs

Deze documentatie wordt meegeleverd met elke Brocade installatie en wordt dan ook behandeld alsof het software is: de reST bestanden worden in qtechng projecten beheerd en dus ook op productieservers geïnstalleerd (indien het tenminste is toegelaten door de brocade.json bestanden). Er is een nachtelijk proces dat deze documenten opspoort en verwerkt tot een geheel dat in zowel HTML als PDF beschikbaar is.

Alle documentatie eenheden in deze rubriek hanteren het Sphinx thema dat neergeschreven is in de registry waarde doc-sphinx-theme en voeren het logo uit de registry waarde doc-sphinx-logo.

Deze documentatie is steeds terug te vinden onder de groep brocade.

1.6.1. Opzetten van Brocade documentatie

De documentatie eenheden werden reeds opgezet en komen telkens overeen met een qtechng project.

In qtechng zijn de volgende projecten gedefinieerd:

/doc/tools

Dit staat voor de documentatie eenheid die de Brocade building blocks beschrijft: de diverse software componenten die de Brocade ontwikkelaars zelf gebruiken (zoals: namespaces, keyvalue, meta, templates. mjson, ...) vinden hier hun plaats.

/doc/m

Dit staat voor de documentatie eenheid die zich bezig houdt met één van de belangrijkste bouwstenen van de Brocade software: de M database

/doc/system

Deze documentatie eenheid beschrijft hoe een Brocade systeem wordt opgezet en onderhouden. Hier worden de primitieve componenten besproken (zoals: operating systems, hardware, networking, ...)

/doc/procedures

Hier worden de diverse procedures beschreven die de Brocade onderhoudsploeg dient uit te voeren. Dit zijn stappenplannen die moeten worden gevolgd bij zaken zoals controle backup, installatie van een nieuwe release op een productieserver, opzetten van een nieuwe beta release, controlepunten bij permanentie, actiepunten bij defecten.

/doc/loan (en aanverwanten)

Hier wordt de ontwikkelde software functioneel beschreven. De diverse toepassingen zoals catalografie, leen, acquisitie worden hier behandeld.

/doc/misc

Diverse documentatie die anders moeilijk te plaatsen is.

/doc/application

Dit is een buitenbeentje: behalve software wordt in dit project ook het documentatie platform zelf gedocumenteerd.

/doc/releases

Opnieuw een speciaal project. De bestanden uit dit project worden op automatische wijze vergaard uit de huidige en de voorgaande releases. Dit project mag niet manueel worden aangepast.

Deze projecten bevatten meestal nauwelijks bestanden. Er is enkel:

  • install.py: de installatie script

  • index.rst: de verwijzingen naar de reële documenten

De *.rst bestanden staan het beste dicht tegen de software waarmee ze verbonden zijn.

Zo kan je /doc/tools/install.py vinden:

from anet.core import installer
installer.restdoc(group="brocade", unit="tools")

index.rst bevat dan iets van de gedaante:

###################################################
Brocade software componenten
###################################################

Deze handleiding beschrijft diverse instrumenten die worden gebruikt bij de ontwikkeling van Brocade software.

De klemtoon ligt op software en methodes die worden gebruikt bij het vervaardigen van de Brocade software zelf.

Inhoud:

.. Bij het plaaten van een qpath als link naar een document hou je best rekening met de volgorde.
.. In het bijzonder: als een technologie B afhankelijk is van A, noteer dan A voor B

.. toctree::
   :numbered:
   :maxdepth: 3

   /universe/meta/namespace.rst
   /universe/stdlib/template.rst
   /keyvalue/doc/keyvalue.rst
   /universe/meta/meta.rst
   /uprocess/application/uprocess.rst
   /stdlib/json/json.rst

1.6.2. Ik ben een Brocade ontwikkelaar. Hoe moet ik ...

... een stukje documentatie testen en bekijken?

Ontwikkelaars werken aan software en aan de documentatie van deze software tegelijkertijd. Het is helemaal niet productief om dan een volledige documentatie eenheid met Sphinx te verwerken om deze documentatie na te kijken. Het is heel wat interessanter om enkel dit ene document te verwerken en de HTML ervan te controleren. Plaats daarom in install.py de opdracht installer.restdoc(rst="myspecific.rst", name="besteversoftware"). Na de gewone qtechng checkin operaties kan de ontwikkelaar de HTML bestuderen op: https://dev.anet.be/rst/besteversoftware. Dit werkt enkel op de Brocade ontwikkelmachine: op productiemachines heeft deze opdracht geen effect.

... documentatie mogelijk/onmogelijk maken?

De registry waarde doc-sphinx-enabled moet expliciet op 1 worden gezet om documentatie mogelijk te maken: delphi -add doc-sphinx-enabled 1. Is deze registry waarde niet gedefinieerd (of staat deze op 0), dan wordt er geen documentatie aangemaakt.

... een PDF bestand aanmaken van de Brocade documentatie?

Bij het produceren van de Brocade documentatie wordt steeds een HTML formaat aangemaakt. Dit formaat kan worden aangevuld met een PDF formaat en/of een ePUB formaat. Zet daartoe de registry waarde sphinx-formats-brocade op bijvoorbeeld pdf, epub en installeer dan de betreffende projecten.

... de Brocade documentatie configureren?

De Brocade documentatie wordt geconfigureerd door de volgende parameters:

  • doc-sphinx-copyright: een korte copyright boodschap (bijvoorbeeld: 2000, Anet)

  • doc-sphinx-enabled: 0 of 1

  • doc-sphinx-logo: een logo (bijvoorbeeld: /library/httpd/htdocs/brocade/layout/doc.png)

  • doc-sphinx-theme: het sphinx thema (bijvoorbeeld: anet)

  • sphinx-formats-brocade: additionele formaten voor Brocade documentatie (bijvoorbeeld: pdf,epub)

  • sphinx-themes-dir: map met additionele Sphinx thema's (bijvoorbeeld: /library/process/sphinx/themes)

... verwijzen naar documentatie?

Laten we een onderscheid maken tussen andere ontwikkelaars en Brocade gebruikers. Een ontwikkelaar kijkt het best op de ontwikkelmachine. Als hij de documentatie van bijvoorbeeld de eenheid tools in de groep brocade wil bekijken, dan is de juiste URL https://dev.anet.be/doc/brocade/tools. Ontwikkelaars hebben vanzelfsprekend ook toegang tot de *.rst bestanden. reST is een zeer leesbaar bronformaat en kan heel goed dienst doen als directe documentatie. Brocade gebruikers zijn het beste af op hun eigen productiemachine (zelfde URL structuur). Het is immers voor hun moeilijk om in te schatten wat de verschillen zijn in de bij hen geïnstalleerde versie en de versie die momenteel in ontwikkeling is.

Warning

Het is geen goed idee om URLs met een /rst te gebruiken als verwijzing naar documentatie. Deze links zijn bedoeld om te worden gebruikt door de auteurs van de documenten. Deze links zijn niet stabiel, kunnen altijd worden verwijderd en staan niet op productiemachines.

1.7. Anet documentatie

Ook deze documentatie komt onder verantwoordelijkheid van het Anet team. Het betreft hier documentatie die gemeenschappelijk is voor de Anet partners.

Deze documentatie wordt eveneens aangemaakt in de qtechng omgeving. Voorbeelden van dergelijke documentatie zijn: catalografisch regelwerk, Impala documentatie, onderwerpsontsluiting, AAT, ...

De groep heet anet en bevat alvast de volgende documentatie eenheden: catalografie, onderwerpsontsluiting, impala.

Anet gaat op bepaalde plaatsen ankerpunten plaatsen in de documentatie. Anet garandeert de stabiliteit van deze ankerpunten. Dit betekent niet dat deze ankerpunten altijd aanwezig zullen blijven: het betekent wel dat er goede redenen moeten zijn om deze ankerpunten te verwijderen of aan te passen en ook dat de gebruikers van deze ankerpunten op de hoogte worden gebracht indien er hier wijzigingen optreden.

Warning

Deze ankerpunten zijn bedoeld om te worden gebruikt binnen de Brocade context: worden deze ankerpunten gebruikt in een andere software, dan vervalt deze garantie.

Aangezien deze documentatie in de qtechng omgeving wordt geplaatst, moeten de projecten waarin deze documentatie wordt gepubliceerd, worden afgeschermd: het is gewoonweg nutteloos deze documentatie zichtbaar te maken in andere dan Anet omgevingen. Plaats daarom in het betreffende qtechng project een bestand brocade.json. Dit bestand bepaalt onder meer of dit project moet worden geïnstalleerd op de productieservers.

Een voorbeeld voor brocade.json:

{
    "groups": "*anet*"
}

Er zijn 2 redenen om de Anet documentatie in qtechng te onderhouden:

  • qtechng werkt met versie controle en release beheer. De documentatie kan hier van profiteren. Moet deze documentatie toch - tussen twee Brocade releases in - worden gepubliceerd op de productieservers, dan wordt de huidige documentatie als een bug beschouwd, deze wordt dan gecorrigeerd en overnacht wordt de aanpassing dan op de Anet servers geïnstalleerd.

  • een tweede reden ligt in de adresseerfaciliteiten van qtechng: elk bestand in het Brocade software repository heeft een stabiele en unieke coördinaat (het qpath). Deze coördinaat kan dan weer worden gebruikt in andere (ook lokale) documentatie groepen en documentatie eenheden. Dit maakt dat Anet documentatie integraal onderdeel wordt van de lokale documentatie. Dit gaat verder dan een eenvoudige link wat trouwens meteen duidelijk wordt uit de layout: de vormgeving is dan niet langer deze van Anet maar wel volgens het lokale thema.

1.8. Lokale documentatie

De diverse instellingen die Brocade gebruiken kunnen ook groepen creëren. Deze kunnen ze dan weer bevolken met documentatie eenheden die lokaal worden aangemaakt. Ze kunnen deze groepen ook aanvullen met documentatie eenheden uit de groep brocade.

De Anet partners kunnen bovendien ook documentatie eenheden kiezen uit de groep anet.

De zoeksoftware garandeert dat telkens de volledige groep wordt geïndexeerd. De linken gaan resultaat opleveren, tenminste zolang deze worden gevolgd binnen de documentatie die Anet ter beschikking stelt.

De auteurs zijn nu personeel van de bibliotheek: hun documentatie inspanningen dienen nu het belang van de bibliotheek.

Onder deze documentiegroep vinden we de volgende inspanningen:

  • documentatie van de diverse procedures die gangbaar zijn in de bibliotheek

  • documentie van de Brocade meta-informatie over hoe deze werd opgesteld ten behoeve van de bibliotheek.

  • diverse bibliotheekregelementen

De documentatie wordt uitgewerkt door een samenwerking van enerzijds het juiste bibliotheekpersoneel dat kennis van zaken heeft en anderzijds de diensten van de Brocade helpdesk. Deze moet immers de juiste parameters instellen zodanig dat de geschreven documentatie op de juiste manier kan worden ontplooid.

1.8.1. Documentatiegroepen

Documentatiegroepen zijn verzamelingen van documentatie eenheden.

Documentatie eenheden zijn eerder thematisch opgezet terwijl documentatiegroepen veeleer organisatorisch (lokaal) zijn georienteerd.

De identifier van een documentatiegroep wordt per Brocade sessie bepaald en volgt een waterval systeem (zodra een passende identifier wordt gevonden stopt het waterval systeem):

  • er wordt gekeken naar de voorkeurinstellingen van de Brocade gebruiker

  • de gegevens van de basisinstelling van de gebruiker worden bevraagd

  • de gegevens van het actuele werkstation worden bevraagd

  • de gegevens van de catalografische instelling worden nagekeken

  • indien dit alles faalt, dan wordt de registry waarde doc-group-default opgevraagd.

Korte naam [projectname: tekst]

Deze naam wordt gebruikt om deze groep te identificeren in de documentatie

Standaard help url [defaulturl: tekst]

Specificeer een URL.

Deze heeft als functie om te verwijzen naar een algemene help pagina indien de specifieke help niet bestaat.

Het is het beste deze URL te specificeren als een absolute path relative url. Dit betekent: beginnend met een '/' en zonder de host naam.

Thema [theme: keuze]

Selecteer het Sphinx thema dat bij deze documentatie groep hoort.

Logo [logo: tekst]

Voer een d-loi in naar een logo.

Is dit veld niet ingevuld, dan wordt het standaard logo uit de Brocade configuratie gebruikt. Een logo is steeds een PNG of een JPEG bestand.

Copyright [copyright: tekst]

Voeg een korte copyright in.

Bijvoorbeeld: 2000, Brocade

Sphinx configuratie [confpy: tekst]

Voer een d-loi in naar een Sphinx configuratiefile.

Is dit veld niet ingevuld, dan wordt de standaard configuratiefile /doc/application/conf.py gebruikt.

Alternatief [alternate: tekst]

Dit is de naam van een andere documentatie group.

Indien eenheden of topics niet bestaan onder de oorspronkelijke groep, dan worden ze gezocht in dit alternatief.

Documentatie eenheden [units: herhaalbaar, meerdere velden]

Noteer (in volgorde) wat de samenstellende delen zijn van de documentatie.

Elk van die samenstellende delen documenteert een specifiek, thematisch onderwerp.

Velden:

  • Documentatie eenheid [metaDocgroup.unit]

  • Sorteercode [metaDocgroup.sort]

1.8.2. Documentatie eenheden

Diverse *.rst documenten worden gegroepeerd tot een documentatie eenheid. Een dergelijke documentatie eenheid wordt beschreven in Brocade meta-informatie.

Documentatie eenheden zijn verzamelingen van documentatie bestanden.

Ze zijn eerder thematisch opgezet. Zelf worden documentatie eenheden verzameld in een groter geheel (de documentatiegroep) die dan weer organisatorisch (lokaal) is georiënteerd.

Deze documentatie eenheden zijn rechtstreeks adresseerbaar op het web.

Algemeen

Informatie over deze documentatie eenheid.

WebDAV [webdav: tekst]

Geef de referentie die verwijst naar de WebDAV omgeving die wordt gebruikt om de documentatie bij te houden. Plaats, behalve de reST documenten, ook afbeeldingen en dergelijke in deze map.

Let ook op de afscherming van deze map.

Taal [lg: tekst]

Specificeer de taal.

reST bestanden [rsts: herhaalbaar, tekst]

Er zijn twee mogelijkheden:

  • De WebDAV folder bevat een bestand met de naam index.rst. Dit bestand bevat dan de naam van alle reST bestanden die deel uitmaken van de documentatie unit. Wordt deze werkwijze gebruikt, dan moet dit veld niet worden ingevuld. Deze werkwijze - met een expliciet index.rst document - geniet de voorkeur.

  • Men kan de reST bestanden hier invullen in volgorde. (Let op de kapitalisatie!). Deze bestanden moeten wel in de WebDAV folder staan. Uitzondering wordt er gemaakt voor de reST bestanden die worden beheerd door Anet en die men wenst op te nemen in de deze documentatie eenheid. Specificeer deze documenten met hun volledige qtechng naam. Vraag hulp aan de helpdesk.

Sorteercode [sort: tekst]

Via de sorteercode kan de volgorde van de eenheden binnen een group gemanipuleerd worden.

Gebruik een 4-letter code die bij alfabetische sortering de eenheid op de juiste plek in het overzicht plaatst.

Bijvoorbeeld sorteercode aafg plaatst de eenheid voor de eenheid met soreercode abfg.

PDF? [withpdf: boolese waarde]

Stip aan of de documentatie ook in de vorm van een PDF bestand moet worden gegenereerd.

ePUB? [withepub: boolese waarde]

Stip aan of de documentatie ook in de vorm van een ePUB bestand moet worden gegenereerd.

Publiceer? [publish: boolese waarde]

Vink aan of deze documentatie mag worden gepubliceerd.

RSS [rssfeed: herhaalbaar, tekst]

Noteer de RSS feed die moeten worden bijgewerkt.

Aantal dagen 'levend' [feedalive: geheel getal]

Noteer het maximum aantal dagen waarop een bericht als 'nieuw' wordt bestempeld.

Up to date [uptodate: geheel getal]

Dit getal geeft aan hoe lang de documentatie up-to-date blijft.

Het is aan te raden dit getal niet te groot te nemen: het systeem verwijdert de documentatie maar maakt deze ook terug aan.

Deze parameter wordt vooral gebruikt om overbodige documentatie te schrappen.

Linken

Beschrijven van linken vertrekkende van andere (meestal algemenere documentatie) naar deze documentatie

Linken vanuit andere documentatie [embed: herhaalbaar, meerdere velden]

Deze faciliteit maakt het mogelijk om linken te plaatsen naar deze documentatie eenheid op automatische wijze:

- de auteur van die documentatie (meestal gaat het over algemenere documentatie) maakt een aantal woorden beschikbaar (de ankerbronnen).
- de auteur van de huidige documentatie kan toelaten dat er in die algemenere documenattie een link onstaat naar het *doel anker*

Velden:

  • Bron documentatiegroep [metaDocunit.docgroup]

  • Bron documentatie eenheid [metaDocunit.docunit]

  • Bron anker [metaDocunit.sourceanchor]

  • Doel anker [metaDocunit.targetanchor]

  • Sorteercode [metaDocunit.sortcode]

  • Titel [metaDocunit.title]

1.9. Ankerpunten in de documentatie

Auteurs kunnen ankerpunten plaatsen binnen de documentatie. Deze ankerpunten beantwoorden volledig aan de reST specificatie. De Brocade documentatie software zorgt er echter voor dat deze ankerpunten ook kunnen worden aangesproken door externe software.

Een ankerpunt heeft een naam die aan de volgende specificaties voldoet:

  • de naam bevat enkel karakters uit [a-z0-9-]

  • de naam moet beginnen met een letter

  • de naam mag niet eindigen op een -

  • in de naam mogen - niet na elkaar staan.

Ankerpunten worden in reST gespecificeerd als:

.. _anker-punt:

Warning

Let op het verschil tussen het minteken en de underscore. Vergeet ook niet het afsluitende dubbelpunt te plaatsen.

1.10. Ankerpunten en uitgaande linken

De hypertechnologie op het web is gebaseerd op uitgaande linken: dit zijn linken (gebaseerd op URLs) die expliciet in het brondocument worden geplaatst en dan toegang bieden tot andere plaaten op het Web.

Dit systeem heeft als voordeel dat de auteur van het brondocument de volledige controle behoudt over zijn document: hij bepaalt welke uitgaande linken er verschijnen.

Echter, soms vind de auteur het best goed dat er uitgaande linken zijn (naar doeldocumenten). Alleen ..., hij wil niet geconfronteerd worden met het onderhoud van deze linken.

Een goed voorbeeld vinden we in het regelwerk voor de Anet catalografie: dit document beschrijft omstandig de regels waaraan een catalograaf zich dient te houden bij het invoeren van een bibliografische beschrijving. Bij zo'n beschrijving is er echter ook plaats voor lokale praktijken: zo is het invoeren van de plaatsingsgegevens in hoge mate gebonden aan de specifieke bibliotheek. Verwacht wordt dat deze lokale regels uitvoerig worden beschreven in een ander - bibliotheek afhankelijke - documentatie. Het is dan ook wenselijk dat in het algemene document een link wordt geplaatst naar deze lokale documentatie.

De werkwijze is als volgt:

  • de auteur van het brondocument (startpunt van de linken) bepaalt waar in het brondocument dergelijke linken beschikbaar komen

  • de praktische elementen (zoals waar precies deze link moet naar verwijzen) wordt door de auteur van het doeldocument behandeld door middel van de meta informatie van de documentatie eenheid en neemt essentieel de vorm van een ankerpunt

1.10.1. Taak voor de auteur van het brondocument

Hij plaatst in zijn brondocument een constructie van de gedaante:

.. link-to-others: <identifier>

link-to-others is een vaste tekst. <identifier> is een identificatie (bevat enkel karakters uit [a-z0-9-]). Met als voorbeeld local-holdinginfo, wordt dit dus:

De auteur van het brondocument communiceert deze identifier aan eventuele gegadigden.

1.10.2. Taak voor de auteur van het doeldocument

De auteur van het doeldocument heeft meer werk:

  • op de juiste plaats, ergens in een rst van het doeldocument, plaatst hij een ankerpunt.

  • in de meta informatie van de corresponderende documentatie eenheid (horende bij het doeldocument) plaats hij:

    • de identifier van dit ankerpunt

    • de verwoording (binnen het brondocument) voor deze link

    • de sorteercode voor deze link (enkel belangrijk indien er meerdere doeldocumenten kunnen zijn)

    • de documentatie groep van het brondocument

    • de documentatie eenheid van het brondocument

    • de identifier bij de link-to-others constructie.

De software van het documentatie platform vervang de link-to-others constructie door een opsomming van uitgaande linken naar de betreffende doeldocumenten.

1.11. Contextgevoelige help boodschappen in Brocade

Warning

Verwar documentatie niet met help boodschappen.

Het is duidelijk dat documentatie en help boodschappen veel met elkaar te maken hebben. Het is echter precies deze gemeenschappelijkheid die voor verwarring zorgt.

Een paar verschillen:

  • niet alle documentatie is bedoeld als contextgevoelige help: documentatie over hoe een Brocade systeem wordt opgezet zal niet vlug opduiken als help in een Brocade formulier.

  • de aanmaak is verschillend: documentatie wordt samengesteld onder de volledige autonomie van de auteur. Contextgevoelige help komt tot stand door samenwerking van twee partijen: de auteur en de software ontwikkelaar.

  • contextgevoelige help bij data entry moet twee heren dienen: hulp hij het omschrijven van welke data moet worden ingevuld (een kennis die zit bij de organisatie die Brocade gebruikt) en hoe deze moet gebeuren (kennis die zit bij de ontwikkelaar).

Als documentatie wordt gebruikt om contextgevoelige help te verschaffen, dan moet deze data-georiënteerd worden uitgebouwd. Het volgende voorbeeld geeft hierover meer inzicht: stel dat men in de lezersadministratie een veld Gebruikersklasse moet invullen. De data die hier moet worden ingevuld is afhankelijk van de persoon die zich aan de balie aanbiedt: een personeelslid wordt bijvoorbeeld anders behandeld dan de gewone lezer. Als de documentatie rond lezersadministratie niet data-georiënteerd is (bijvoorbeeld: de documentatie bevat een hoofdstuk Behandeling van personeelsleden waarin alles wordt verzameld dat te maken heeft met personeelsleden en een hoofdstuk Behandeling van niet-personeelsleden), dan zal de documentatie geen verfijnde, adequate contextgevoelige help kunnen aanbieden. Is de documentatie echter data-georiënteerd, dan zal er zeker een paragraaf Gebruikersklasse voorkomen met instructies over hoe de diverse personen, die zich bij de balie aandienen, moeten worden beschreven.

Note

Merk meteen de schaduwzijde op van een data-georiënteerde aanpak: deze is heel nuttig voor personeel die aan data-entry doet, maar is heel wat minder interessant voor een bibliotheekgebruiker. Het voorbeeld geeft het onderscheid goed aan: in de niet-data georiënteerde aanpak staan alle aspecten van de afhandeling van bijvoorbeeld een personeelslid bij elkaar. Om al deze aspecten te ontdekken bij de data-georiënteerde aanpak, moet de lezer ook alle data elementen bekijken.

1.11.1. Hoe wordt data ingevuld?

Het specificeren van deze informatie is de taak van de Brocade ontwikkelaar. Dit gebeurt meestal door het specificeren van een scope note in markdown formaat. Deze tekst wordt dan op diverse wijzen gecommuniceerd met de gebruiker.

Soms bevat het formulier onmiddellijk deze informatie. Dit is gemakkelijk vanuit het oogpunt van de software ontwikkelaar maar leidt tot overvolle formulieren met informatie die de ervaren Brocade gebruiker van achter naar voor kan afdreunen.

De beste methode is deze van het context menu: enkel indien de gebruiker om de informatie vraagt, wordt deze ook getoond.

1.11.2. Welke data wordt ingevuld?

Dit is een veel moeilijker te beantwoorden vraag. Er is immers vaak veel meer context nodig om een adequaat antwoord te formuleren. De Brocade aanpak is om te verwijzen naar een plek in de gebruikersdocumentatie. Deze gebruikersdocumentatie is zaak van de bibliotheek: deze weet precies de regels waar de software gebruiker zich dient aan te houden.

Om contextgevoelige documentatie mogelijk te maken werkt Brocade met 6 parameters:

group

De documentatiegroep. Deze parameter wordt geassocieerd met de Brocade gebruiker, zeg maar zijn affiliatie.

handle

Deze parameter wordt gegeven door de software ontwikkelaar en identificeert de Brocade toepassing.

topic

Ook deze parameter wordt door de software ontwikkelaar gegeven en identificeert het data veld.

unit

De documentatie eenheid zoals deze wordt opgesteld door de auteur van documentatie.

anker

Een ankerpunt in de documentatie. Ook deze wordt aangeduid door de auteur van de documentatie.

url

Dit is een URL naar web georiënteerde documentatie. Wordt automatisch berekend.

Werken binnen deze structuur biedt heel wat voordelen:

  • opsplitsen van de verantwoordelijkheden: de documentatie auteurs en software ontwikkelaars kunnen autonoom aan de slag.

  • deze opsplitsing maakt het ook mogelijk om andere dan op Sphinx gebaseerde documentatie systemen te gebruiken als contextgevoelige help.

1.11.3. Hoe wordt de group bepaald?

De documentatiegroep wordt berekend bij elke nieuwe pagina van Brocade. Hiertoe wordt gebruik gemaakt van de macro getDocgroup.

macro getDocgroup($docgroup, $staff="", $catlib="", $workstation=""):
    '''
    $synopsis: Haal naam op van de documentatiegroep
               Dit volgt een watervalsysteem: van zodra een documentatiegroep wordt gevonden,
               stopt de waterval.
               - eerst wordt in de persoonlijke voorkeuren van de Brocade gebruiker gekeken.
               - vervolgens wordt in de basisinstelling van het personeelslid gekeken.
               - dan wordt in het actuele werkstation gezocht
               - vervolgens in de basisinstelling van het werkstation
               - tenslotte wordt de registry waarde "doc-group-default" gehanteerd.
    $docgroup: Documentatiegroep (te berekenen)
    $staff: id personeelslid (vb. rphilips)
    $catlib: id catalografische instelling (optioneel)
    $workstation: id werkstation (optioneel)
    $example: m4_getDocgroup(RDdocgrp, "rphilips")
    '''
    «s $docgroup=$$%Group^docwinfo($staff,$catlib,$workstation)»

1.11.4. Hoe wordt de handle bepaald?

Het is de software ontwikkelaar die de handle vast legt. Hij maakt hiervoor gebruik van de *.b files. In deze bestanden worden immers de menuitems gedefinieerd. Bij een menu-item kan een attribuut dochandle worden gespecificeerd. Deze is dan meteen de bewuste handle. De waarde van de handle voldoet aan de reguliere uitdrukking [a-z][a-z0-9]*. Het beste wordt een term gekozen met een Engelstalige basis.

De group en de handle worden ter beschikking gesteld in de M-variabele UDmanual onder de vorm group.handle.

Deze variabele kan door de ontwikkelaar worden gemanipuleerd.

Tenslotte wordt deze variabele ook ter beschikking gesteld in het web formulier door middel van de macro:

m4_manual(x4_varruntime(UDmanual), defaulttopic, docsys=sphinx)

Note

Alle schermen bij een zelfde menu-item krijgen dezelfde handle. De ontwikkelaar kan deze in de software wel aanpassen.

Diverse menu-items kunnen dezelfde handle krijgen.

1.11.5. Hoe wordt de topic bepaald?

De topic wordt rechtstreeks gekoppeld met het data element. Aan het bewuste widget (HTML element) die het data element representeert, kan een attribuut data-help worden gegeven. Dit attribuut bevat precies de waarde voor de topic.

Het is vanzelfsprekend opnieuw de ontwikkelaar die de topic specificeert.

De topic heeft een naam die aan de volgende specificaties voldoet:

  • de naam bevat enkel karakters uit [a-z0-9-]

  • de naam moet beginnen met een letter

  • de naam mag niet eindigen op een -

  • in de naam mogen - niet na elkaar staan.

Opnieuw wordt het best een term gekozen met een Engelstalige basis.

De ontwikkelaar doet er goed aan om deze namen goed te specificeren volgens het principe verwante data elementen krijgen topics die slechts een wildcard uit elkaar liggen.

In het catalografisch formulier krijgen de data elementen die over de titel van de beschrijving gaan, een topic die begint met title-.

Topics kunnen ook nog op andere manieren worden bepaald. Bij de specificatie van de handle in de *.b file kan ook een default topic worden gespecificeerd. Deze wordt dan gescheiden van de handle met een .. Ook in de macro kan een default waarde voor de topic worden gegeven. Blijft de waarde voor de topic onbepaald, dan wordt de waarde op unknown gezet.

Tenslotte is er nog de mogelijkheid om topics door de software zelf te laten genereren: met elke HTML widget komt immers een naam in het Web formulier. Deze naam wordt door de ontwikkelaar gegeven en voldoet aan de zonet vastgelegde regels.

Het contextgevoelige help systeem van Brocade bepaalt de topic in cascade:

  • bestaat het data-help attribuut (en is het niet leeg), dan wordt dit gekozen.

  • leidt de naam van de widget (attribuut name) tot een geldige topic naam dan wordt dit gekozen.

  • tenslotte kan ook de default name worden gebruikt.

1.11.6. Wat is de unit?

De unit staat voor de documentatie eenheid. De auteur stelt deze samen, op autonome wijze maar met kennis van zaken en inzicht hoe de documentatie gaat worden gebruikt als contextgevoelige help.

1.11.7. Wat is een anchor?

Een anchor staat voor een ankerpunt. De auteur plaatst deze ankerpunten op autonome wijze in de *.rst bestanden die horen bij een unit. Hij beseft dat deze ankerpunten kunnen worden gebruikt bij het aanbieden van contextgevoelige help.

1.11.8. Wat is de url?

De url is een hyperlink naar de contextgevoelige help. Is de DNS van de productiemachine bij voorbeeld anet.uantwerpen.be, dan is url steeds:

https://anet.uantwerpen.be/help/group/handle/topic

Dit betekent nog dat de url steeds door de browser is gekend en dat de browser rechtstreeks kan linken naar de contextgevoelige help.

De Apache webserver gaat deze url omzetten naar:

https://anet.uantwerpen.be/help.phtml?group=group&handle=handle&topic=topic

De script achter help.phtml gaat dan (group, handle, topic) omzetten naar url.

Dit wordt mogelijk gemaakt door de documentatie verbindingen.

1.11.9. Wat zijn documentatie verbindingen ?

Documentatie verbindingen maken het mogelijk om de Brocade software te koppelen aan concrete documentatie.

Er zijn 5 parameters die een rol spelen in de verbinding:

Vanuit de software:

  • handle: dit is een identificatie van de documentatie die hoort bij de actieve Brocade toepassing

  • topic: dit is een identificatie van een specifiek onderdeel in de toepassing

Vanuit de context:

  • group: gebruikers krijgen documentatie afhankelijk van de lokatie waar ze werken

Vanuit de concrete documentatie:

  • unit: de specifieke handleiding

  • anchor: de precieze plaats in deze handleiding.

De gegeven waarden (group, handle, topic) worden opgezocht in de lijst met verbindingen. Daar waar ze overeenkomen, worden (unit, anchor) geselecteerd. Het reST bestand met anchor als een ankerpunt wordt opgezocht en daarmee wordt dan ook de url samengesteld.

In de lijst met documentatie verbindingen hoeven de topics niet exact worden ingegeven: hier kunnen ook wildcards worden gebruikt.

Documentatiehandle [dochandle: tekst]

Dit is een software constructie: dit gegeven wordt meegedeeld door de Brocade ontwikkelaars.

Deze documentatiehandle kunnen de ontwikkelaars zelf steeds terugvinden in de b-bestanden. De menuitems die documentatie dragen worden voorzien van een extra attribuut dochandle. In de Brocade toepassing staat deze waarde steeds in de variabele UDmanual.

Topic [topic: tekst]

Ook dit is een constructie uit de software: de Brocade ontwikkelaars merken bepaalde plaatsen in het formulier met deze codes.

Documentatiegroep [docgroup: herhaalbaar, tekst]

Dit is de documentatiegroep die van toepassing is op de gebruiker.

Documentatie eenheid [docunit: tekst]

De documentatie eenheid staat voor documentatie over een bepaald thema.

Ankerpunt [anchor: tekst]

Dit is een HTML anker. Geef de naam zoals het in de documentatie zelf voorkomt.

1.11.10. Gehele Brocade toepassing linken aan een (plek in) document

Vaak zal het niet nodig zijn om de contextgevoelige documentatie uit te werken op het niveau van de velden of categorieën, maar is het voldoende om een gehele toepassing (meta groep) te koppelen aan een specifiek rst-document. Dit zou je kunnen doen door bij de verbindingen voor het topic een * te gebruiken. Het kan echter ook ter hoogte van de b-file opgelost worden.

Voorbeeld:

meta welcome:
  $attribute: doc
      $$content: _system
      $$value: brocade.system.welcome

Via het attribuut doc kan je een link leggen naar de juiste documentatie volgens notatie group.unit.anchor. Op deze manier zal er voor bovenstaand voorbeeld in een formulier van meta-groep welcome steeds gelinkt worden naar het rst-document in group Brocade, unit System en met naam welcome.rst.

1.12. Extra instrumenten voor documentatie auteurs

Bovenop het standaard instumentarium van Sphinx, biedt Brocade nog een ganse verzameling van instrumenten om het documentatieproces te versoepelen.

1.12.1. Plaatsen van een referentie

Sphinx heeft diverse faciliteiten voor het plaatsen van referenties (:ref: constructies). Brocade speelt hier op in door deze faciliteit uit te breiden. De link (de tekst achter :ref:) kan worden gestructureerd met behulp van punten.

Er moet minstens 1 punt voorkomen in de link (indien er geen . voorkomt in de link, dan blijft de standaard Sphinx functionaliteit van toepassing). Het gedeelte voor het eerste punt is dan steeds de group, het gedeele na het eerste punt en voor het tweede is de unit, de (eventuele) derde component is dan het anchor.

:ref:`link naar ander document in reST <group.unit.anchor>`

Is het gedeelte voor het eerste punt leeg, dan wordt hier de actuele groep in geplaatst. Is het tweede gedeelte leeg, dan wordt hier de actuele unit in geplaatst.

Het is aan te raden om, als de verwijzingen binnen de groep gebeuren, zeker het eerste gedeelte leeg te houden: gebeurt dit niet, dan wordt, bij het overnemen van documentatie tussen groepen, verwezen naar de verkeerde groep.

Brocade verwerkt de link als volgt:

  1. ontbreekt het anchor, dan gaat de hyperlink naar het startpunt van de documentatie van unit binnen group

  2. bestaat het anchor in de unit van de group, dan gaat de hyperlink naar deze positie

  3. bestaat het anchor niet in de unit van de group, dan contoleert het systeem of er een rst bestand bestaat met dezelfde naam als het anchor. Zo ja, dan gaat de hyperlink naar het begin van die pagina.

  4. indien dit document ontbreekt, dan gaat de hyperlink naar het startpunt van de documentatie.

1.12.3. Automatisch inbedden van meta-informatie

Meta-informatie (nieuwe stijl) in Brocade is in hoge mate gestructureerd en gedocumenteerd. Deze structuur kan worden omgezet in passende reST.

Auteurs kunnen de corresponderende reST gemakkelijk inbedden door een reST commentaar veld van de gedaante:

.. brocade-meta: metatype

Hierbij staat metatype voor de identifier van het type meta-informatie waarvan de documentatie moet worden ingebed.

1.12.4. Automatisch inbedden van informatie omtrent een gebruikersproces

Ook Brocade gebuikersprocessen zijn in hoge mate gestructureerd en gedocumenteerd. Deze structuur kan worden omgezet in passende reST.

Auteurs kunnen de corresponderende reST gemakkelijk inbedden door een reST commentaar veld van de gedaante:

.. brocade-uprocess: uprocessid

Hierbij staat uprocessid voor de identifier van het gebruikersproces waarvan de documentatie moet worden ingebed.

1.12.5. Werken met Brocade menu-ingangen

Sphinx heeft een methode om een menuselectie te tonen. Hiermee is het mogelijk om ook Brocade menuselecties te styleren.

Het volgende voorbeeld toont wat dit bijvoorbeeld betekent voor het invoeren van archiefbeschrijvingen:

:menuselection:`Impala toepassing <https://dev.anet.be/menu/brimwgo>`__

Deze omslachtige methode kan beter worden vervangen door het volgende:

:menucall:`brimwgo`

Het documentatiesysteem zorgt zelf wel voor het inlassen van de nodige verwoordingen en linken.

1.12.6. Verwijzingen naar de issue tracker

Verwijzingen naar de issue tracker komen veelvuldig voor. Om bijvoorbeeld te verwijzen naar issue 2372 gebruik je het best de constructie:

:issue:`2372`

Het documentatiesysteem herleidt dit naar:

`Issue 2372: Fout in template <https://anet.be/tracker/brocade/issue2372>`__

1.12.7. Inlassen van macro's

Brocade ontwikkelaars maken veelvuldig gebruik van macro's. Deze worden in de qtechng ontwikkelomgeving uitvoerig gedocumenteerd. Deze documentatie kan eenvoudig worden ingebed door middel van de constructie:

.. code-block:: macro macronaam

Vanzelfsprekend moet je macronaam vervangen door de naam van de macro.

1.12.8. Inlassen van een qtechng bestand

Gebruik de constructie:

.. qinclude: indent qpath

Hierbij is:

  • indent: een getal die extra indentation aangeeft

  • qpath: het qpath van het betreffende bestand

Voorbeeld:

.. qinclude: 4 /doc/variable/udip.rst

1.12.9. Inlassen van de naam van een Brocade gebruiker

Verwijzingen naar een Brocade gebruiker (personeelslid) doet men het best op de volgende wijze:

:staff:`rphilips`

Het documentatiesysteem vertaalt dit als volgt:

`Richard Philips <richard.philips@uantwerpen.be>`__

1.12.10. Inlassen van een tekstfragment

Brocade telt een grote collectie van codes die vertaald werden in het Nederlands, Frans en Engels. Van deze codes kan worden gebruik gemaakt op twee verschillende wijzen.

1.12.10.1. Inline opnemen van een code

Een vertaling inline opnemen kan met behulp van de volgende constructie:

De code `metaDocgroup.theme.scope` wordt verwoord tot: :text:`metaDocgroup.theme.scope`

Het documentatiesysteem vormt dit om tot:

De code `metaDocgroup.theme.scope` wordt verwoord tot: Selecteer het *Sphinx* thema dat bij deze documentatie groep hoort.

1.12.10.2. Markdown vertaling van een code

Tekstfragmenten kunnen ook worden opgenomen als een blockelement in Markdown. Gebruik daarvoor de volgende constructie:

.. markdown: metaDocgroup.theme.scope

Dit wordt omgevormd tot:

Selecteer het *Sphinx* thema dat bij deze documentatie groep hoort.

1.12.11. Output van M code

Documentgenerators geven de mogelijkheid om delen van documentatie te genereren.

Het documentatie onderdeel komt tot stand door M code uit te voeren die op standaard output schrijft.

Documentgenerators worden gebruikt om een beveiligingsprobleem uit de weg te gaan: het is immers niet wenselijk de code zelf te specificeren in de documentatie.

Code [do: tekst]

Specificeer de uit te voeren M code.

RDlg bevat de taal waarin de documentatie is geschreven.

Deze code schrijft op standaard output. Het resultaat wordt ingebed in de documentatie.

1.12.12. Verwijzingen naar documenten

Een Brocade systeem kan verschillende andere documenten beheren. Elk van deze documentsoorten hebben hun eigen mogelijkheden en hun eigen gebruik. Het Brocade documentatie systeem biedt handige verwijzingsvormen naar deze documenten. Deze bieden bovendien het voordeel dat ze bestand zijn tegen een herconfiguratie van het computersysteem.

1.12.12.1. Pagina's uit een Wiki

In Brocade kunnen Wiki's worden geïnstalleerd. Deze hebben tot doel de informele kennis van het bibliotheekpersoneel te vatten: handige weetjes die niet direct een plek vinden in de officiële documentatie.

Zo bevat de adbib Wiki van de UA-biblioheek een pagina Wireless in de bibliotheek. Het best wordt er naar deze pagina verwezen als volgt:

:wiki:`Wireless in de bibliotheek <adbib/Wireless%20in%20de%20bibliotheek>`

1.12.12.2. Bestanden uit de fileserver

In Brocade worden administratieve elementen (aangemaakt door het personeel van de bibliotheek) beheerd op een fileserver. De technologie die daarvoor wordt gebruikt is WebDAV. Deze technologie gaat heel goed samen met de web natuur van Brocade.

Het bibliotheekpersoneel plaatst zelf documenten (meestal Office documenten) op de fileserver. Opnieuw bestaat er meta-informatie die de mappenstructuur van de fileserver organiseert en er ondermeer toegangsrechten aan toekent.

De fileserver van de UA-bibliotheek bevat een document met als hyperlink https://doc.anet.uantwerpen.be/webdav/ua/jaarverslag/2014/Jaarverslag%202014%20StorifyBC_V1.pdf. Deze link wordt het eenvoudigst opgespoord met behulp van een webbrowser. Het best is naar dit document te verwijzen als:

:webdav:`Jaarverslag 2014 <ua/2014/Jaarverslag%202014%20StorifyBC_V1.pdf>`

Daar er geen kopie wordt gemaakt van het document, blijven de toegangsrechten gerespecteerd.

1.12.12.3. Automatisch gegenereerde documenten

Een andere klasse van documenten zijn deze die door het bibliotheeksysteem zelf worden gegenereerd of bijgehouden: het gaat hier over allerlei briefwisseling die door Brocade zelf wordt aangemaakt (rappels, bestellingen) maar ook over documenten die door Brocade worden beschreven in diverse applicaties.

Goede voorbeelden van deze laatsten zijn:

  • ingescande afbeeldingen

  • verhandelingen door laatste jaar studenten

  • wetenschappelijke publicaties al dan niet in Open Access.

Deze documenten worden ontsloten door middel van een coördinaat die er uitziet als een pad naam in een Unix file systeem, maar toch onafhankelijk is van de gekozen technologie of opslagsysteem. Zo is /preciosa/fffd99/trs0268.png een referentie naar een thumbnail.

Het best wordt naar dit document verwezen als:

:docman:`Thumbnail </preciosa/fffd99/trs0268.png>`

1.12.12.4. Documenten op het web

Tenslotte zijn er nog de documenten die zich niet (noodzakelijk) op de webservers van de UA bevinden. Deze documenten worden beschreven in een Brocade toepassing die docstore heet. Behalve de nodige informatie om deze documenten te kunnen lokaliseren, is het ook mogelijk om hier extra informatie aan te koppelen zoals: auteurs, titels, trefwoorden. Deze documenten worden gekarakteriseerd door een d-loi. Een d-loi is steeds iets van de gedaante d:ua:6727. Het best wordt er gerefereerd op de volgende wijze:

:dloi:`d:ua:6727`

Het documentatie systeem maakt daar een URL van en - indien aanwezig - wordt ook de titel vermeld.

1.12.12.5. Epiloog

Om te vermijden dat iedereen telkens de veelgebruikte replacements opnieuw moet aanvullen onderaan een document, werd doc/application uitgebreid met een epilog.sphinx bestand. Alles wat hierin staat wordt telkens na uitvoering van de config.py toegvoegd aan het einde van een rst-document.

Voorbeeld:

Wanneer je in het rst-document |UA| noteert, zal de epiloog er voor zorgen dat dit zal vervangen worden door

.. |UA| replace:: :abbr:`UA (Universiteit Antwerpen)`

Je hoeft dus zelf die replace niet te noteren.

UA_ zal vervangen worden door .. _UA: https://www.uantwerpen.be

|UA|_ zal vervangen worden door zowel de afkorting als de link.

Het epilog.sphinx bestand kan uiteraard ook uitgebreid worden met andere replacements of andere elementen die standaard onderaad een rst-document moeten worden toegvoegd.

1.13. Communicatie van aanpassingen

Nieuw of gewijzigd!

Over RSS feeds

Het aanpassen van documentatie (of gewoonweg, het publiceren van documentatie) kan meteen gaan dienen als een mijlpaal voor de personeelsleden van een bibliotheek.

Een paar voorbeelden:

  • documentatie van het nieuwe bibliotheekreglement betekent meteen ook dat het balie personeel dit nieuwe reglement gaat toepassen.

  • aanpassingen aan het regelwerk voor de catalografie zijn een signaal voor de titelbeschrijvers dat de nieuwe regels ook in voege treden.

Het is dus zaak dat belanghebbenden zo goed mogelijk op de hoogte worden gehouden van deze aanpassingen. Vanzelfsprekend bestaan er daarvoor verschillende hulpmiddelen: e-mail, nieuwsbrieven, personeelsvergaderingen.

Deze worden echter het best aangevuld met een instrumentarium dat nauw verbonden is met de documentatie zelf.

Brocade ondersteunt RSS faciliteiten en deze kunnen worden gebruikt om de belanghebbenden op de hoogte te brengen van aanpassingen aan de documentatie.

In Brocade kunnen diverse RSS feeds worden gedefinieerd. Achter dergelijke feeds schuilt een URL. Een webgebruiker kan zich dan, via deze URL, abonneren op een dergelijke feed. Daartoe heeft hij een juiste client nodig om deze feed te gebruiken. Dergelijke clients kunnen geïntegreerd zijn in Webbrowsers, Mailclients. Ze kunnen in de Cloud bestaan of op mobiele platformen. Er zijn RSS lezers die thuis horen op de desktop, anderen kunnen dan weer een SMS versturen.

Anders dan bij een webpagina, moet je niet zelf op zoek naar nieuwe informatie: deze komt vanzelf bij jou terecht. Het is ook anders dan een mail client: het is de gegadigde zelf die uitmaakt of hij iets kan aanvangen met de informatie en hij is meteen onafhankelijk of de zender hem wel opneemt in het lijstje met de geaddresseerden.

Wie een RSS feed wenst te voorzien voor een of meerdere documentatie eenheden, gaat best als volgt te werk:

  1. Feed definiëren: Via RSS feeds [link] moet de nieuwe feed gedefinieerd worden. Gebruik hiervoor best een kopie van de feed doc.

  2. Feed koppelen aan de juiste documentatie eenheid: Via Documentatie - Eenheden [link] kan de juiste RSS feed aan deze eenheid gekoppeld worden. Wijzigingen in documentatie van deze eenheid die via een notify worden aangeduid, zullen in de RSS feed terecht komen. Bijkomend kan je ook aangeven hoeveel dagen de feed als nieuw moet beschouwd worden.

    Note

    Een feed koppelen aan een documentatie eenheid dient te gebeuren in de Brocade toepassing. Dat wil zeggen dat eenheden die enkel in qtechng gedefinieerd zijn, nu ook in Brocade moeten beschreven worden met de juiste meta-informatie.

  3. Gewijzigde hoofdstuk markeren in de documentatie: Het is de auteur die bepaalt welke aanpassingen op de RSS feed komen. Hij plaatst daartoe op strategische plaatsen in de documentatie (het best net voor de hoofdstukken of secties die moeten worden gecommuniceerd) zogenaamde notify instructies:

    .. notify: yyyy-mm-dd Vrije tekst met meer duiding over de wijziging.
    

    Op basis van deze lijn worden er 3 gegevens verzameld:

    • het tijdstip vanaf wanneer de informatie moet worden gecommuniceerd

      Note

      de datum wordt in ISO formaat YYYY-MM-DD genoteerd

    • een informatielijn

    • uit de documentatie wordt de eerste titel opgepikt die komt na de notificatielijn.

    Merk nog op dat de feednaam zelf ontbreekt. Deze informatie wordt uit de meta-informatie gehaald die Brocade bijhoudt over de eenheid. Daar staat ook het aantal dagen genoteerd die aangeeft hoelang een item nieuws-waardig is.

    Warning

    Enkel wanneer er ook effectief een wijziging wordt opgeslagen in het document, zal de RSS feed aangemaakt worden. Enkel de notify aanduiding wegschrijven is dus niet voldoende.

In het automatisch proces docpublish dat elke ochtend loopt, worden de RSS feeds aangemaakt.

Om een RSS feed te lezen, moet de URL van de feed genoteerd worden in een mailprogramma of RSS reader.

http://[server]/docman/rssfeeds/p[feedid].rss

[server]

Hier komt de server waarom de feed zal lopen. Gaat het om attenderingen op documentatie op legato (dev.anet.be) of om documentatie op moto (anet.be)?

[feedid]

Dit is de identificatie van de feed die werd aangemaakt in Brocade onder RSS feeds [link]

In de documentatie zelf zal onderstaand tekstvak verschijnen, net onder de titel van het hoofdstuk.

_images/imgnotify.png

Onderaan op de inhoudspagina van de documentatie eenheid worden de gewijzigde onderdelen ook vermeld.

_images/imgnotify2.png