Documentatie, van last naar kracht
•Download as PPSX, PDF•
0 likes•865 views
Documentatie, van last naar kracht - Anke Jacobs, Richard Philips
Recommended
Recommended
More Related Content
Similar to Documentatie, van last naar kracht
Similar to Documentatie, van last naar kracht (20)
More from Vlaamse Vereniging voor Bibliotheek, Archief & Documentatie vzw (VVBAD)
More from Vlaamse Vereniging voor Bibliotheek, Archief & Documentatie vzw (VVBAD) (20)
Documentatie, van last naar kracht
- 1. Documentatie, van last naar kracht Informatie aan zee – 18 september 2015 Anke Jacobs & Richard Philips
- 2. If people don’t know why your project exists, they won’t use it. If people can’t figure out how to install your software, they won’t use it. If people can’t figure out how to use your software, they won’t use it.
- 3. 3
- 4. Specifiek Beknopt Relevant Voorziet in alle informatie van belang voor de gebruiker van de documentatie. Goede documentatie 4
- 9. Actieve gebruikers Bibliotheekpersoneel • Onervaren Brocade gebruikers nieuw in dienst – jobstudenten – vrijwilligers – tijdelijke mensen • Frequente Brocade gebruikers ervaring – steeds dezelfde module – routine - basisfuncties • Expert Brocade gebruikers A-Z kennis – beheersfuncties van een module • Brocade gangmakers verantwoordelijke module – opzetten meta informatie – opleiding - Anet
- 11. Eindgebruikers Bib management Actieve gebruikers Niet-actieve gebruikers Ontwikkelaars
- 12. Ervaring eerdere projecten • De auteur is het meest kostbare goed in de documentatieketting • Documentatie moet mooi zijn • Documentatie moet worden hergebruikt • Documentatie moet binnen handbereik zijn • Documentatie moet doorzoekbaar zijn
- 14. Een gedachtenexperiment (I) • Laten we catalografische beschrijvingen behandelen zoals we dat met documentatie doen … • We openen een Word-document • We noteren onze beschrijving • We denken WEL na over de layout (bladschikking, lettertype, kleur, …) • We bewaren het document onder de naam van het moment • We bergen dit document veilig en vooral onbereikbaar op
- 15. Een gedachtenexperiment (II) • Deze aanpak is niet bruikbaar: • Te moeilijk om in te bedden in toepassingen (publiekscatalogus, leen) • Nauwelijks raadpleegbaar • Moeilijk aanpasbaar • Omslachtig en vooral te statisch • We zouden dit onze ergste vijand niet aandoen • Maar wel onze gebruikers, collega's, onze vrijwilligers, tijdelijke werkkrachten, jobstudenten, overheden.
- 16. Documentatie als Data (I) • Traject in de UAntwerpen • HyperLib (HTML 3.2 gebaseerd): SGML structuur
- 17. Documentatie als Data (II) • Traject in de UAntwerpen • DocBook: XML structuur
- 18. Documentatie op het Internet (I)
- 19. Documentatie op het Internet (II) • Tekst georiënteerde systemen • `asciidoc` • http://www.methods.co.nz/asciidoc/ • Markdown
- 20. Documentatie op het Internet (III) • reST
- 21. Documentatie op het Internet (IV) • reST • Aan te maken met eenvoudige instrumenten • Kan worden bewaard in een databank • Sphinx productie keten • Leesbaar • Rigoureus en (dus) programmeerbaar
- 22. Documentatie op het Internet (V) • reST (toch XML :-)
- 23. Documentatie op het Internet (VI) • reST als XML • Programmeerbaar • Dynamisch • Sommige elementen uit het bibliotheeksysteem worden opnieuw gebruikt • Layout • Aanpasbaar met 'begrijpbare' technologie • Verschijningsvormen • HTML, PDF, ePUB • Herbruikbaar in andere toepassingen
- 24. Hergebruik van documentatie (I) Voorbeeld: Lezergegevens
- 25. Hergebruik van documentatie (II) Voorbeeld: Lezergegevens
- 26. Ervaring naar keuzes Markup reST
- 27. Ervaring naar keuzes Markup reST Sphinx
- 28. Sphinx • Een toepassing die intelligente en mooie documentatie kan creëren en publiceren vanuit reST. • Oorspronkelijk gemaakt voor Python documentatie. • Weergave van hiërarchische structuur • Werken met templates (open source) 28
- 30. 30
- 31. 31
- 32. Ervaring naar keuzes Markup reST Sphinx WebDAV
- 33. Ervaring naar keuzes Markup reST Sphinx WebDAV Lucene
- 34. Kers op de slagroom op de taart: Zoeken via Lucene
- 37. Ervaring naar keuzes Markup reST Sphinx WebDAV Lucene OpenSource
- 38. Ervaring eerdere projecten • De auteur is het meest kostbare goed in de documentatieketting • Documentatie moet mooi zijn • Documentatie moet worden hergebruikt • Documentatie moet binnen handbereik zijn • Documentatie moet doorzoekbaar zijn
- 40. Ervaring eerdere projecten • De auteur is het meest kostbare goed in de documentatieketting • Documentatie moet mooi zijn • Documentatie moet worden hergebruikt • Documentatie moet binnen handbereik zijn • Documentatie moet doorzoekbaar zijn
- 41. Lokale documentatie Ook onze partners kunnen dit platform gebruiken om documentatie aan te maken, en te koppelen aan een formulier. • Elke organisatie • Eigen documenten aanmaken • Eigen look and feel toepassen • Integratie van bestaande documenten van Anet/Brocade • Auteurs personeel van de bibliotheek • Platform WebDav en Brocade toepassing Voorbeeld UAntwerpen Lezersdiensten
- 42. Verschillende aanbiedingsvormen • Inline bij de toepassing • Pure reST • HTML of PDF versie van reST • Contextgevoelige help: ? • /*Commentaar in de code*/ • Rechtermuisknop in formulier meta informatie
- 44. Ervaring eerdere projecten • De auteur is het meest kostbare goed in de documentatieketting • Documentatie moet mooi zijn • Documentatie moet worden hergebruikt • Documentatie moet binnen handbereik zijn • Documentatie moet doorzoekbaar zijn
- 45. Tot slot • Documentatie schrijven is manueel werk motiveren, inbedden in proces • Vraagt tijd • Ervaring • Afspraken maken rond stijl, structuur, taal, … Anet style guide • Eindredactie • Openheid Vertrouwelijke informatie
- 46. Anke.Jacobs@uantwerpen.be Richard.Philips@uantwerpen.be Links naar bestaande documentatie zijn terug te vinden via anet.be > Documentatie
- 47. Nuttige links • reStructured Text http://docutils.sourceforge.net/rst.html • Sphinx http://sphinx-doc.org/ • Lucene https://lucene.apache.org/ • Webdav http://www.webdav.org/
Editor's Notes
- Documentatie is een zeer ruim begrip: context en afbakening van het begrip documentatie Software documentatie. Brocade als praktijkvoorbeeld gebruikersdocumentatie (hoe werkt het systeem?) en technische documentatie (om het systeem te onderhouden) Bij uitbreiding documentatie over de bibliotheek en haar werkprocessen.
- Documentatie is vaak een minder besproken aspect van software ontwikkeling, toch van groot belang. Laten weten dat je software bestaat en wat het allemaal kan doen. Hoe te installeren, van start gaan Hoe effectief gebruiken om bepaalde zaken te realiseren Toch, het is een essentieel onderdeel van software engineering. Degelijke documentatie komt de kwaliteit van de software ten goede, Het kan er eveneens voor zorgen dat de ontwikkeling van nieuwe software(elementen) en het onderhoud van reeds bestaande elementen efficiënter kan verlopen. Documentatie die goed geschreven is, overzichtelijk gestructureerd en makkelijk toegankelijk is een meerwaarde voor de software waarvoor ze geschreven is, zal bijdragen tot het succes van die software.
- Valkuilen van een productieproces (eender wat) Documentatie komt meestal wel voor in het stappenplan van een project, maar hoe het wordt ingevuld is niet altijd even oke. Want laat ons eerlijk zijn, de meeste projectmanagers en teamleden zijn meer geïnteresseerd in het inhoudelijke projectresultaat, dan in de documentatie. Deze cartoon is uiteraard een erg uitvergrote karikatuur, maar toch (helaas) wel herkenbaar. Projectdocumentatie wordt teveel stiefmoederlijk behandeld, tot groot ongenoegen van de klant/eindgebruiker. Vele discussies en problemen zijn op het einde van de Project Life Cycle dan ook het gevolg van onzorgvuldige einddocumentatie. Documentatie zou ook beter continu tijdens het proces opgebouwd worden, eerder dan op het einde van het proces. Documenteren is communiceren. Maar genoeg gezeurd. Laat ons dan zelf de eerste stap zetten om het allemaal beter te doen. Ik probeer althans bij jullie dat knopje om te draaien.
- Wat is voor jullie goede documentatie? Denk aan een document dat je goed vond en vraag je af waarom je dat goed vond? Je moet de lezer geven wat hij nodig heeft, maar ook niet te veel. Lezer verschillende doelgroepen en andere noden Laat ons daar eens naar kijken. Vind alles terug wat hij nodig heeft snel niet te veel, niet te weinig
- = bibliotheekbezoekers Gebruikt de afgeleide toepassingen van de bibliotheeksoftware - catalogus doorklikken op bol. Eenvoudig zoeken, geavanceerd zoeken HULP knop - online gebruikersdiensten zoals reserveren, verlengen, IBL - attendering inlogscherm, overzicht beschikbare profielen - desktop Weinig documentatie nodig, zou intuïtief moeten zijn Enkel wat online hulp aanbieden, ingebed in de toepassing voorbeeld van opac, inlogscherm, SDI Inline info wordt beschreven in de meta informatie van de toepassing en kan per instelling op maat geschreven worden (eigen voorbeelden die aanspreken) Vandaag dus verder niet behandelen
- Vooral een beleidsaspect: nodig bij audits om te verantwoorden wat er allemaal gebeurd in een bibliotheek, hoe de processen lopen en dus, welke investering er zal moeten tegenover staan. Of om nieuwe medewerkers al zelfstandig (deels) te laten inwerken. Keuze maken om een open politiek te voeren en dus alles beschikbaar te maken voor iedereen. Je geeft dus en inkijk in interne procedures en dergelijke. niets te verbergen en als men iets in vraag wil stellen (kritisch zijn) dan zal er meer argwaan zijn als men geen documentatie vindt, dan wanneer men het kan nakijken … Deze invalshoek ik belangrijk om mee te hebben, maar zal vandaag ook niet verder aan bod komen
- Balanceren. Je kan niet voor elk van die gebruikers eigen documentatie schrijven. Wel kan je dezelfde documentatie op verschillende manieren gaan aanbieden en de keuze aan de gebruiker laten. Hij bepaalt zelf hoeveel documentatie hij wil en wanneer hij dat wil zien. Een ervaren gebruiker kan bijna blindelings door bijvoorbeeld een catalografie formulier lopen en werkt snel. Hij wil niet bij elk veld geconfronteerd worden met toelichting over wat en hoe. Een nieuwe gebruiker leest misschien (eenmalig) graag eens door de gehele documentatie van A-Z. Voor ieder wat wils. Komen we later nog op terug
- Potentiele Brocade gebruikers Medewerkers van een instelling die mogelijk in de toekomst met Brocade zullen werken of mensen die in het kader van een lastenboek willen nagaan wat Brocade te bieden heeft. Ontwikkelaars van andere bibliotheekautomatiseringssystemen Dit kan belangrijk zijn voor de koppeling van andere bibliotheeksystemen met Brocade, bijvoorbeeld in het kader van Impala (Open URL principe).
- Schrijven de broncode. Anet maar ook CiBLiS Je zou denken dat ze de code/software door en door kennen. Veel ja, maar alles heeft zijn grenzen en een heel team dat samen moet werken en op elkaar moet inspelen, verder bouwen … Had ik nu maar opgeschreven waarom ik dat gedaan heb? Je code/software wordt er beter van. Je moet bewust stilstaan bij elke stap in het proces en de logica van de toepassing. Je zal over zwakheden vallen die je dan nog kan verbeteren Anno 2015, bedraagt het totaal aantal bestanden (ook diegene die niet rechtstreeks de databank veranderen) 27.138 bestanden. Dit is in het totaal 380 Mbyte. Release 1.04 uit 2001 was in totaal 70 Mbyte. Pure txt!
- Vanuit HyperLib project veel geleerd! Jaren ‘90 Auteur: ontwikkelaar, gangmaker, experten Mooi: voldoening geven, niet zoals hyperlib Hergebruikt: geen dubbel werk, herschrijven Handbereik: zoeken, integreren
- De ervaring die we hebben opgedaan, voornamelijk uit het HyperLib project, maar ook uit testen met DocBook en gewoon ook voortschrijdend inzicht hebben ons tot volgende keuzes gebracht naar tools die we zullen gebruiken Andere markup talen: HTML, SGML, Markdown, XML
- Hier in detail op ingaan zou ons te ver leiden en te technisch worden. Open source dus ook anderen die hier bijkomende toepassingen op ontwikkelen waar je ook van kan gebruik maken. Python, programmeertaal, ook, niet bij toeval gebruikt voor Brocade Hierarchische structuur: eenvoudige opbouw van de inhoudstafel, met automatische links naar zelfde, hoger en lager niveau
- Magic box toverstafje
- 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.
- 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. Open source tool (API) die uitgebreide zoekmogelijkheden mogelijk maakt
- Op niveau van rst document, niet op niveau van hoofdstuk of alinea Snippet komt uit rst , en dus netjes om te lezen Enkel zoeken in unit Geen booleaanse operatoren en wildcards
- Auteur: gebruik van reST, Sphinx Mooi: via Sphinx kan je makkelijke mooie dingen maken, al neem je gewoon een template van iemand anders (open source)
- Extra snufjes die het werk vergemakkelijken en meer mogelijkheden bieden voor uniforme documenten
- Auteur: gebruik van reST, Sphinx, extra hulpmiddeltjes Hergebruik: velden worden al beschreven in de software. In de documentatie niet overtypen, maar integreren. aanpassingen in de code, worden meteen ook doorgetrokken naar de documentatie. We staan al redelijk ver nu met onze documentatie. rST Sphinx HTML/PDF Anet heeft echter nog meer plannen Maar daarvoor moeten we eerst een structuur opzetten voor onze documentatie
- Mooi systeem opgezet voor documentatie van Brocade en Anet. Nu we dit hebben, willen we het toepassingsgebied zo ruim mogelijk maken. Software op zich, maar ook hoe de software gebruikt wordt per binnen elke instelling. Lokale afspraken en procedures. Voorbeeld integreren van documenten van andere groep Doorlinken naar documenten van een andere groep Meta informatie van de groep Meta informatie van de eenheid Sphinx thema
- Als informatie nieuwe stijl beschikbaar is, dan heeft het linken naar deze info via ? Weinig zin, want idem. Beter is dan om achter het vraagteken documentatie te stoppen die eerder handelt over de lokale afspraken hieromtrent, of de bredere context van het formulier. Zo krijgen we alle info bij binnen handbereik bij de Brocade gebruiker en heeft hij zelf in de hand, welke info hij precies wil raadplegen.
- Voor elke gebruiker de juiste vorm van documentatie Ervaren gebruiker : kan snel door het formulier gaan om alle gegevens in te vullen Sporadische gebruiker kan via klik in veld, rechtsmuisknop extra info over een veld opvragen Nieuwe gebruiker: kan naar uitgebreide en meer algemene documentatie gaan via ? Of nog beter is om daar de lokale vertaalslag te maken van hoe deze toepassing gebruikt/ingevuld dient te worden voor jouw instelling en dus je eigen documentatie achter deze knop te steken.
- Auteur: gebruik van reST, Sphinx Hergebruik: velden worden al beschreven in de software. In de documentatie niet overtypen, maar integreren. aanpassingen in de code, worden meteen ook doorgetrokken naar de documentatie.
- Heel boeiend, maar zeker niet op 123 opgezet. Werk van lange adem en daardoor zit je ook enige tijd met een wat onstabiel systeem (wisselende links, structuur). Toch, de moeite waard!