Sluiten

Softwaredocumentatie automatisch updaten

Bij het ontwikkelen en onderhouden van documentatie staan technical writers voor een heleboel uitdagingen. Het is namelijk niet eenvoudig om een perfecte consistentie te verzekeren tussen een softwareapplicatie en de bijhorende documentatie. Gelukkig kent Flow hier wel een aantal oplossingen voor. Eén zo’n oplossing is het hergebruiken van softwarestrings in je technische documentatie.

Documentatie hinkt vaak achterop

Bij een softwareapplicatie zoals een gebruikershandleiding, onlinehulp of een API-referentiegids, hoort documentatie. Je wil natuurlijk dat de terminologie in je documentatie consistent is met de terminologie in de gebruikersinterface, zoals de tekst in dialoogvensters en menucommando’s. Dat geldt uiteraard ook voor je vertaalde documentatie.

Deze consistentie is er misschien wel in de eerste versie van de documentatie, maar is dit ook het geval in latere versies, naargelang de software geüpdatet wordt? Als de tekst uit de gebruikersinterface simpelweg overgetypt werd in de documentatie, dan betekent elke nieuwe software-update extra werk. Je moet dan de volledige documentatie doorspitten om inconsistenties op te sporen en weg te werken, zowel in de brontaal als in vertalingen.

Softwarestrings gebruiken

Gelukkig bestaat er een betere manier om deze uitdaging aan te pakken. Je kunt de tekst uit je softwareapplicaties, oftewel de “softwarestrings”, hergebruiken in je documentatie aan de hand van een dynamische link. Het proces verloopt als volgt:

  1. Je exporteert de tekst uit de softwareapplicatie naar een gestructureerd bestandsformaat, zoals XML, CSV of JSON. Aan elke softwarestring wijs je bovendien een uniek ID-nummer toe.
  2. Vervolgens transformeer je dat bestand naar een DITA-bestand, waarin de softwarestrings omgezet zijn in herbruikbare componenten.
  3. De technische schrijvers typen de softwarestrings niet langer over in de documentatie. Ze voegen ze in in hun tekst vanuit een centrale opslagplaats van herbruikbare componenten. Op die manier creëren ze een dynamische link. De juiste softwarestring wordt aan de hand van het uniek ID-nummer automatisch opgehaald uit de opslagplaats en weergegeven in de documentatie.
  4. Bij elke update herhaal je enkel de eerste twee stappen van het proces. Opnieuw exporteer je de tekst uit de softwareapplicatie en transformeer je het resulterende gestructureerd bestand met softwarestrings naar een opslagplaats van herbruikbare componenten.

Pas updates automatisch aan

Bij elke wijziging in de softwarestrings van de applicatie, volgt een automatische wijziging in de bijhorende documentatie. De dynamische link zorgt er immers voor dat elke wijziging in de centrale opslagplaats van herbruikbare componenten ook doorgevoerd wordt in de documentatie, dankzij de unieke ID-nummers van de softwarestrings (die ongewijzigd blijven).

Wijzigingen worden via een dynamische link automatisch ingevoerd in de vertaling

Uiteraard geldt dit proces ook voor de updates van vertalingen. De softwarestrings uit de vertaalde softwareapplicatie worden geëxporteerd, getransformeerd en via een dynamische link automatisch ingevoerd in de vertaalde documentatie. Het spaart je medewerkers een heleboel tijd en werk uit!

Geïnteresseerd?

Flow kan helpen dit proces in de praktijk te brengen. Contacteer ons vrijblijvend voor meer informatie.