Linux at the office

Docmenta is een open source cross media publishing webapplicatie. Je gebruikt het ter ondersteuning van het in teamverband maken en beheren van te publiceren documentatie, voor zowel digitale als gedrukte media.

 Veel organisaties werken met documentatie voor klanten of voor intern gebruik, bijvoorbeeld handleidingen, gebruiksvoorschriften, werk-instructies, tutorials, hulp-bestanden, enzovoorts. Dit kan documentatie in de eigen taal zijn, maar soms kan het ook gaan om publicaties die in meerdere talen beschikbaar moeten zijn. Bij een toenemend aantal publicaties stijgt de noodzaak om dit goed te organiseren. Met Docmenta bouw je structuur en ordening en krijg je goed gemanagede processen. Verder kan Docmenta op basis van de brondocumenten de uiteindelijke publicatievorm voor je genereren, waardoor dingen minder snel mis kunnen gaan en het werk efficiënter verloopt.

 Docmenta is een webapplicatie voor het maken en beheren van documentatie, handleidingen, help-files en dergelijke. Het is een single source publishing oplossing, dat wil zeggen dat je één brontekst onderhoudt en die vervolgens naar één of meer formaten exporteert, bijvoorbeeld PDF, HTML, WebHelp, EPUB of DocBook. Het systeem voorziet in het werken met meerdere talen voor dezelfde bron. Docmenta werkt met versie- en releasemanagement en biedt de mogelijkheid om met verschillende rollen en rechten te werken, zoals auteurs, vertalers, goedkeurders en publicatie-managers.

 Teamwork

Docmenta maakt teamwork mogelijk. Een publicatie kan in zijn geheel door één enkele persoon geschreven worden, ook is het mogelijk dat meerdere personen tegelijk aan verschillende delen van de publicatie werken. Docmenta ondersteunt beide mogelijkheden en doordat het een web-applicatie is, maakt het daarbij niet uit of de auteurs naast elkaar in de gang zitten of geografisch verspreid zijn.

 Wanneer een nieuwe publicatie start, krijgt deze automatisch de status “Work in Progress”. Is een auteur klaar met een bepaalde onderdeel, dan zet deze de status om naar “Ready for Approval”. Vervolgens kan iemand die daartoe gerechtigd is de status wijzigen naar “Approved”. Nadat alle onderdelen van een publicatie de status “Approved” hebben, kan Docmenta de publicatie gaan generen naar keuze, in één of meer output-formaten. Je krijgt dan bijvoorbeeld een epub e-book, een pdf-document en een html-publicatie voor het intra- of internet. Vervolgens is het mogelijk om aan een nieuwe versie van dezelfde publicatie te werken, die ook weer de verschillende stadia van “Work in progress” tot en met “Approved” moet doorlopen.

 Docmenta werkt op basis van producten. Een product is iets waarover je handleidingen en dergelijke wilt maken, dus bijvoorbeeld een bepaalde versie van een computerapplicatie, een bepaald model fiets of een bepaald medicijn. Per product maak je een structuur bestaande uit meerdere onderdelen, bijvoorbeeld afbeeldingen en teksten. Teksten kun je weer opbouwen uit verschillende secties, enzovoorts. Hiermee maak je het mogelijk dat verschillende mensen tegelijk aan hetzelfde document werken. De beheerder maakt gebruikersgroepen en gebruikers aan, waarbij een gebruiker in meerdere groepen kan zijn opgenomen. De toekenning van rechten gaat per product op basis van gebruikersgroepen.

 Wanneer je de te maken publicatie in verschillende onderdelen of secties opdeelt, dan geeft dit later de mogelijkheid om de onderlinge volgorde te wijzigen, zonder dat daarvoor de inhoud van die onderdelen hoeft te worden gewijzigd. Het is dus zowel vanuit het oogpunt van werkverdeling als ook vanuit het oogpunt van het beheer van de structuur van de publicatie zinvol om bijvoorbeeld voor elk hoofdstuk een apart onderdeel te maken. Verder kun je ook met includes werken om bepaalde onderdelen op meer plekken te laten terug komen en biedt Docmenta de mogelijkheid om met content-filtering te werken. Hiermee kun je bij het maken van de export bepaalde delen weg te filteren, terwijl je die bij een andere export juist wel mee neemt.

 Naast de vooraf gedefinieerde stijlen kun je in Docmenta zelf stijlen toevoegen. Deze stijlen betreffen een bepaald gedeelte van de brontekst, zoals bijvoorbeeld een stijl voor blokken aanvullende toelichting. Je kunt meerdere varianten op zo’n stijl maken, bijvoorbeeld een printvariant voor pdf-exports en een webvariant voor HTML-pagina’s. Deze zelf toegevoegde stijlen zijn in alle producten toe te passen.

 Pop-up

Een auteur gaat aan een tekst werken door in zijn werkgebied het product te openen en op een onderdeel te dubbelklikken. Het systeem opent een nieuw window waarin een WYSIWYG-editor geopend wordt. Wij moesten daarom eerst in onze browser het openen van pop-upvensters toestaan. Het systeem heeft nu een check-out vlaggetje gezet en de auteur kan de tekst gaan onderhouden. Het check-out vlaggetje voorkomt dat anderen tegelijk aan dezelfde sectie werken en wijzigingen gaan opslaan. Wij hebben in de WYSIWYG-editor geen mogelijkheid tot spellingscontrole gevonden, dit moet de auteur dus anders regelen. De WYSIWYG-editor is een javascript-editor, met alle bekende functies, zoals vet, cursief, paragraaf-header, opsommingen, enzovoorts, inclusief de mogelijkheid om tabellen op te nemen.

 In Docmenta kun je templates gebruiken om vaker voorkomende onderdelen (bijvoorbeeld een tabel met een bepaalde indeling die je geregeld moet gebruiken) eenmalig aan te maken en deze vervolgens – waar nodig – in je tekst op te nemen.

 De tekst die de auteur maakt, vormt straks de bron die we naar één of meer publicatievormen gaan exporteren. Het systeem kiest hierbij of, en waar, er page-breaks komen. De auteur kan hierop wel invloed uitoefenen door het invoegen van een page-break op een bepaalde plaats of juist bij een blok aan te geven dat deze een geheel moet blijven. Verder heeft de auteur de mogelijkheid om diverse stijlen toe te passen, afbeeldingen op te nemen, verwijzingen naar andere delen te maken, links op te nemen, enzovoorts.

 Afbeeldingen

Afbeeldingen dienen eerst te worden geüpload voordat zij in de tekst kunnen worden opgenomen. Voordat je een afbeelding gaat uploaden, moet je vooraf goed nadenken over de naam van het bestand. Je kunt een bestandsnaam maar één keer per product gebruiken. Deze beperking is vooral een aandachtspunt wanneer je met verschillende auteurs binnen hetzelfde product werkt. In zulke gevallen is het handig om hierover vooraf met elkaar afspraken te maken. Overigens kun je meerdere bestanden in een keer uploaden door ze eerst in een zipfile te stoppen. Je refereert aan afbeeldingsbestanden via een alias, dit is de bestandsnaam zonder de extensie.

 Nadat het uploaden van de afbeelding is voltooid, voeg je deze in je tekst in. In de WYSIWYG-editor klik je met de cursor op de betreffende plaats op de button met een plaatje van een boom als icoontje. Je krijgt nu een pop-up window waarin je de alias van het bestand invult en wat aanvullende gegevens (waarmee bijvoorbeeld later de alt-tekst van de afbeelding in de HTML-code wordt gegenereerd). Het is dus handig om de bestandnamen van je afbeeldingen vooraf slim te kiezen, zodat deze laatste stappen vlotjes verlopen.

 Versiebeheer

Het systeem houdt automatisch de wijzigingen bij. Iedere keer wanneer je een wijziging opslaat, wordt dit als revision weggeschreven. Deze revisions kun je per onderdeel opvragen, het systeem toont per revision de datum waarop deze is opgeslagen samen met de naam van de betreffende persoon. Wanneer je twee revisions kiest, krijg je de tekst te zien waarbij de wijzigingen via kleuren herkenbaar zijn.

 Soms wil je in de tekst verwijzen naar een ander deel van de tekst, bijvoorbeeld een afbeelding of een tabel in een ander hoofdstuk. In HTML zou je dat kunnen doen door een “klik hier” linkje, maar dat is niet bruikbaar in gedrukte vorm. Docmenta biedt daarom de mogelijkheid om interne referenties te maken. Hierbij wijs je naar een anker in een bepaalde sectie en wordt automatisch de juiste verwijzing gegenereerd.

 Docmenta geeft in één oogopslag een globaal beeld van de voortgang van het werk. Bij het aanmaken van de structuur onder het product geef je per onderdeel op wat de prioritiet is; laag, normaal of hoog. Per onderdeel toont het systeem een percentage om aan te geven hoever het werk gevorderd is. Dit gebeurt op basis van informatie die de auteurs invoeren. Wanneer je met de rechtermuisknop op het onderdeel klikt, krijg je een submenu, met o.a. de optie “Edit properties”. Je krijgt nu een pop-up waarin je met behulp van een slider dit percentage aanpast en een opmerkingen-veld van tekst kan voorzien. In het overzicht met verschillende onderdelen staat de status (“work in progress”, “approved” etc.) en het percentage. Wanneer het opmerkingen-veld niet leeg is, dan verschijnt hier een klein tekstballonnetje en afhankelijk van de prioriteit is deze lichtblauw, geel of rood. Ga je met de muis over dit ballonnetje, dan zie je de ingevoerde opmerking als hoover-tekst.

 Meertalige publicaties

Bij het initiëren van een nieuw product in Docmenta geef je de taal of talen op die van toepassing zijn. Eén taal is altijd het origineel, de andere taal of talen zijn vertalingen. Je kunt voor ieder soort node vertalingen opvoeren, dus niet alleen voor teksten, maar ook voor afbeeldingen etc. Ook hierbij heb je de mogelijkheid om in één oogopslag de stand van zaken te zien. In het administratieve gedeelte kun je per product aangeven wie vertaalrechten krijgt. Docmenta levert je dus ook voor meertalige publicaties goed beheerde processen inclusief voortgangsbewaking.

 Installatie

Docmenta is geschreven in Java en wordt verspreid onder de LGPL licentie. Het installeren van Docmenta is niet ingewikkeld. Docmenta is een Java applicatie die een bijbehorende webserver gebruikt, bijvoorbeeld de Apache Tomcat server. Om Docmenta te installeren, kun je uit verschillende methodes kiezen. De meest eenvoudige methode is om te kiezen voor de download met daarin zowel Docmenta als de Tomcat server. Je hebt dan alleen nog een Java Runtime Environment (JRE) nodig. Wij installeerden op Debian Wheezy het package openjdk-7-jre. Hierna is het een kwestie van de zipfile downloaden en unzippen. Na het unzippen vind je een directory /apache-tomcat-7.0.55 met daarbinnen verschillende subdirectories, cd naar de bin directory. Hier moet je nog even de .sh-bestanden executable maken (chmod +x), waarna je eenvoudig ./startup.sh kunt draaien. Nadat de server draait, open je in je browser http://ipnummer:8080/docmenta/setup om de configuratie af te ronden. Hierbij kies je onder andere de directory waar de werkbestanden komen, bijvoorbeeld /usr/lib/docmenta. Deze directory moet uiteraard beschrijfbaar zijn voor de tomcat-server. Vergeet niet deze directory mee te nemen in je back-up procedures.

 Volwassen processen

Invoering van Docmenta levert de organisatie flinke stappen op naar een volwassen procesbeheersing. Je hebt meteen een aantal zaken goed voor elkaar. Docmenta is een goede oplossing voor het complete proces, van planning tot en met productie van de uiteindelijke publicaties. Het zorgt voor een goede werkverdeling en een goed procesmanagement. Het ingebouwde versiebeheer, van zowel de brontekst revisions als de versies van de uiteindelijke publicaties, kan alleen al een reden zijn om hiervoor te kiezen. Docmenta ziet er niet super flitsend uit, maar je kunt er snel mee aan de slag. Het is echter wel een op zichzelf staande omgeving. Zaken als import van bestaande groepen en bestaande gebruikers of koppelingen met bestaande gebruikers-directoties, zoals LDAP, missen. Voor grotere organisaties kan dit een belemmering zijn. Afgezien hiervan lijkt ons Docmenta een mooie open source oplossing. Je krijgt een degelijk product in huis waarmee veel organisaties een slag kunnen maken om de totstandkoming van diverse publicaties verder te professionaliseren.