Eine großangelegte Umfrage zu Open Source zeigt, dass unvollständige oder verwirrende Dokumentation zu den Hauptproblemen freier Software zählt [1]. Das gilt neben Anwendungsdokumentation insbesondere auch für technische Dokumentation, etwa von Softwarearchitektur. Diese Aussage können wir sicherlich verallgemeinern: schlechte Dokumentation von Software erschwert Änderung, Support und letztlich auch Nutzung. Wir möchten hier auf technische Dokumentation von Software abzielen, also beispielsweise Entwicklungs-, Architektur- und Betriebsdokumentation. Das Thema Anwendungsdokumentation klammern wir bewusst aus.

Unserer Erfahrung nach behindern eine ganze Reihe von Faktoren die Erstellung und kontinuierliche Pflege technischer Dokumentation:

1. Ungeeignete Werkzeuge, die ursprünglich nicht für die Erstellung und Pflege solcher Dokumentation gedacht waren.
2. Geringe Motivation seitens der Entwicklungsteams, oftmals verstärkt durch die oben genannten Defizite der entsprechenden Werkzeuge.
3. Unklare Vorstellung über Struktur, Form und Inhalt von Dokumentation: Entwicklungsteams haben keine klare Vorstellung davon, was und wie sie dokumentieren sollen.
4. Schlechte Vorlagen ("Templates") für Dokumentation.

• Docs-as-Code – Teil 2: Die Werkzeuge
• Docs-as-Code – Teil 3: Alles unter einem Dach
• github.com: Docs-as-Code: (technische) Dokumentation in gut
• github.com: docToolchain
• Doc-As-Code project home

I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… their Firefox addon sends to Diigo every single URL you visit (Don't believe me ? Use Tamper Data and open any page).

Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.