documentatie, van last naar kracht
TRANSCRIPT
Documentatie, van last naar kracht
Informatie aan zee – 18 september 2015Anke Jacobs & Richard Philips
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
4
Specifiek Beknopt Relevant
Voorziet in alle informatie van belang voor de gebruiker van de documentatie.
Goede documentatie
Eindgebruikers
Eindgebruikers
Bib management
Eindgebruikers
Bib management
Actieve gebruikers
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
Eindgebruikers
Bib management
Actieve gebruikers
Niet-actieve gebruikers
Eindgebruikers
Bib management
Actieve gebruikers
Niet-actieve gebruikers
Ontwikkelaars
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 …
Waarom een nieuw documentatieplatform?
Documentatie verspreidNauwelijks doorzoekbaarNiet te vinden op plaats en moment waarop je het
nodig hebtVerschillende stijlenNiet meer up to date
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
Ervaring naar keuzes
Markup reST
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
Ervaring naar keuzes
Markup reST
Sphinx
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)
18
Documentatie - Auteurszijde
19
20
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
Lucene
Ervaring naar keuzes
Markup reST
Sphinx
WebDAV
Lucene
Ope
n So
urce
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
Aan de slag: schrijven van documenten
• Teksteditor Notepad++ , Komodo Edit, Textadept, Kladblok
• reST• Sphinx converteert naar mooie HTML (en PDF/ePub)
Alles kan beter!
OpenSource Software
Ontwikkelaars
Extra snufjes
Maatwerk
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
Structuur van documentatiegroep
eenheden
bestanden
eenheden
groep
Structuur van documentatie
Index.rst
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.
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
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
Documentatie verbindingen
Documentatie - kant
• Group
• Unit• Anchor
Software - kant
• Handle• Topic
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
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
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
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• …
Waarom een nieuw documentatieplatform?
Documentatie verspreidNauwelijks doorzoekbaarNiet te vinden op plaats en moment waarop je het
nodig hebtVerschillende stijlenNiet meer up to date
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
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
[email protected]@uantwerpen.be
Links naar bestaande documentatie zijn terug te vinden via anet.be > Documentatie