documentatie, van last naar kracht
TRANSCRIPT
![Page 1: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/1.jpg)
Documentatie, van last naar kracht
Informatie aan zee – 18 september 2015Anke Jacobs & Richard Philips
![Page 2: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/2.jpg)
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.
![Page 3: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/3.jpg)
3
![Page 4: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/4.jpg)
4
Specifiek Beknopt Relevant
Voorziet in alle informatie van belang voor de gebruiker van de documentatie.
Goede documentatie
![Page 5: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/5.jpg)
Eindgebruikers
![Page 6: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/6.jpg)
Eindgebruikers
Bib management
![Page 7: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/7.jpg)
Eindgebruikers
Bib management
Actieve gebruikers
![Page 8: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/8.jpg)
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
![Page 9: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/9.jpg)
Eindgebruikers
Bib management
Actieve gebruikers
Niet-actieve gebruikers
![Page 10: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/10.jpg)
Eindgebruikers
Bib management
Actieve gebruikers
Niet-actieve gebruikers
Ontwikkelaars
![Page 11: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/11.jpg)
Anet, nog niet zo slecht bezig
Documentatie beschikbaar Brocade Verbeter Voorstellen [HTML] Handleiding voor Leen, Aanwinsten, … [HyperLib] Regelwerk Anet catalografie [HyperLib] Handleiding Impala [Word/PDF] Slides opleiding [PowerPoint] …
Contextgevoelige documentatie vanuit catalografie naar regelwerk vanuit aanwinsten naar handleiding …
![Page 12: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/12.jpg)
Waarom een nieuw documentatieplatform?
Documentatie verspreidNauwelijks doorzoekbaarNiet te vinden op plaats en moment waarop je het
nodig hebtVerschillende stijlenNiet meer up to date
![Page 13: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/13.jpg)
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
![Page 14: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/14.jpg)
Ervaring naar keuzes
Markup reST
![Page 15: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/15.jpg)
reStructured Text (reST)
• Plaintext markup• Ontwikkeld voor Python documentatie
• Makkelijk te lezen• WYSIWYM• Rigoureus• Kan goed geformatteerd worden• Makkelijk om te zetten in HTML/PDF/ePUB via Sphinx
Markdown, in software zelf voor kortere teksten
![Page 16: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/16.jpg)
Ervaring naar keuzes
Markup reST
Sphinx
![Page 17: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/17.jpg)
17
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)
![Page 18: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/18.jpg)
18
Documentatie - Auteurszijde
![Page 19: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/19.jpg)
19
![Page 20: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/20.jpg)
20
![Page 21: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/21.jpg)
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
![Page 22: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/22.jpg)
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
Lucene
![Page 23: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/23.jpg)
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
Lucene
Ope
n So
urce
![Page 24: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/24.jpg)
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
![Page 25: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/25.jpg)
Aan de slag: schrijven van documenten
• Teksteditor Notepad++ , Komodo Edit, Textadept, Kladblok
• reST• Sphinx converteert naar mooie HTML (en PDF/ePub)
![Page 26: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/26.jpg)
Alles kan beter!
OpenSource Software
Ontwikkelaars
Extra snufjes
Maatwerk
![Page 27: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/27.jpg)
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
![Page 28: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/28.jpg)
Structuur van documentatiegroep
eenheden
bestanden
eenheden
groep
![Page 29: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/29.jpg)
Structuur van documentatie
![Page 31: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/31.jpg)
En alsof dat nog niet voldoende was
Niet alleen documentatie vanuit Anet.
Ook onze partners kunnen dit platform gebruiken om documentatie aan te maken, en te koppelen aan een formulier.
![Page 32: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/32.jpg)
Lokale documentatie
• Groep Brocade en Anet, voorbehouden• Elke organisatie kan zijn eigen groep aanmaken.
• Eigen documenten• Eigen look and feel• Integratie van documenten/eenheden van Anet/Brocade
• Auteurs personeel van de bibliotheek• Platform WebDav en Brocade toepassing
Voorbeeld UAntwerpen Lezersdiensten Brocade Documentatie toepassingen
![Page 33: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/33.jpg)
Slagroom op de taart: contextgevoelige documentatie
• Verbinding tussen software en documentatie• Vanuit een Brocade toepassing • Tot op niveau van een specifiek veld• Context: toepassing & group• Uitvoering: Anet
‘Slimme documentatie’
Documentatie ≠ help boodschap
Voorbeeld Meta informatie magazijnbeheer
![Page 34: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/34.jpg)
Documentatie verbindingen
Documentatie - kant
• Group
• Unit• Anchor
Software - kant
• Handle• Topic
![Page 35: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/35.jpg)
Bepalen van de groep: cascade
Gerelateerd aan instelling (documentatie groep)Bepaald door cascade:1. Voorkeursinstellingen gebruiker2. Basisinstelling gebruiker3. Werkstation4. Catalografische instelling5. Registry waarde doc-group-default
![Page 36: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/36.jpg)
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
![Page 37: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/37.jpg)
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
![Page 38: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/38.jpg)
Kers op de slagroom op de taart: Zoeken via Lucene
• Via Sphinx: zoekscherm beschikbaar• Zoeken binnen index /unit
• Te ontwikkelen: zoekscherm via Lucene• Zoeken binnen group• Filters• …
![Page 39: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/39.jpg)
Waarom een nieuw documentatieplatform?
Documentatie verspreidNauwelijks doorzoekbaarNiet te vinden op plaats en moment waarop je het
nodig hebtVerschillende stijlenNiet meer up to date
![Page 40: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/40.jpg)
Voordelen nieuw documentatieplatform?
DoorzoekbaarheidUniform in look and feel per instellingSterk te automatiseren (makkelijk voor auteur)Raadplegen in HTML – PDF – Epub - …Kort bij de toepassing (qtech/webdav)Herbruiken van documenten en tekstfragmentenKoppelen aan Brocade formulieren
![Page 41: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/41.jpg)
Tot slot
• Documentatie schrijven is manueel werk motiveren, inbedden in proces
• Vraagt tijd• Ervaring• Afspraken maken rond stijl, structuur, taal, …
Anet style guide• Eindredactie
• Keerzijde• Openheid Vertrouwelijke informatie• Bepalen van de groep
![Page 42: Documentatie, van last naar kracht](https://reader036.vdocuments.net/reader036/viewer/2022062515/55d706c6bb61eb9a468b4597/html5/thumbnails/42.jpg)
[email protected]@uantwerpen.be
Links naar bestaande documentatie zijn terug te vinden via anet.be > Documentatie