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

Anke.Jacobs@uantwerpen.beRichard.Philips@uantwerpen.be

Links naar bestaande documentatie zijn terug te vinden via anet.be > Documentatie