Documentation 03.07.2019

Do not document the obvious. Documentation for SOA Do not document the obvious. 03.07.2019

Many documentation look like the user manual of a microwave oven sold to US. 03.07.2019

Most alleged documentation is nothing more than an exhaustive Write-Only-Memory (WOM) 03.07.2019

Documentations are not novels They are for finding information quickly in a case of need 03.07.2019

Documentation must be precise and easy to read It needs to be intuitive It needs to be easy to read 03.07.2019

Bad documentation is worse than no documentation Falsche Dokumente können kontraproduktiv sein Es sollte dabei auch jedem bewusst sein, dass falsche oder falsch aufbereitete Dokumente unter Umständen das Gegenteil dessen bewirken können, was mit ihnen beabsichtigt ist. Ein besonders häufig in allen Organisation zu beobachtender Missstand sind zu umfangreiche Dokumente. Dabei wird mit hartnäcker Ignoranz außer Acht gelassen, dass nicht das Schreiben, sondern das Lesen – also die Weitergabe von Information – der alleinige Zweck der Dokumente sind. Es muss natürlich auch immer gesehen werden, welche Absicht man mit der Dokumentation in erster Linie verfolgt, etwa die Schulung späterer Mitarbeiter, Bescheibung des guten Funktionierens mit Hinweisen zur Störungsbehebung oder die protokollierung für den Fall eines Audit bei Regressansprüchen. 03.07.2019

Documenting software is a service. Leave it to the documentation experts. 03.07.2019

Technical writers cannot program Programmers cannot write documentation Ausbildung im Verfassen von Dokumentation Wie jede auf Beständigkeit und Qualität ausgelegte und hochwertigeArbeit, erfordert auch das Erstellen von Dokumentation eine Ausbildung. Es kann nicht bezweifelt werden, dass Mitarbeiter einer IT-Organisation sehr unterschiedliche Voraussetzungen zum Erstellen der Dokumentationen mitbringen. Es kann deshalb nicht von den Mitarbeitern als selbstverständlich erwartet werden, dass diese auch nur annähernd die Fähigkeit zum Erstellen von Dokumentationen besitzen. Genauso wie eine Schulung in Technologien stattfindet, muss deshalb auch eine Einweisung und ggf. tiefergehende Schulung im Dokumentieren stattfinden. 03.07.2019

What is a good documentation 03.07.2019

Better documentation Wikipedia Request for Comments (RFC) Team can make changes quickly Request for Comments (RFC) Allow anybody to comment Add a discussion forum Blend support emails into documentation Wikipedia will everybody allow everybody to enhance the documentation. Encourage people to comment. Not everybody wants to change other peoples work if they are not 100% sure; comments allow a moderated way to enhance the documentation. In W3C this is called RFC = request for Comments. Issue tickets for problems and use technology to attach the emails threads to the appropriate topics. 03.07.2019

Classic documentation hindered people to make changes This makes people ignorant They know the mistake but have better things to do 03.07.2019

Like always: You cannot expect cooperation if you make it hard You have to reward people for good deeds Not punish them 03.07.2019

Documentation Guidelines 03.07.2019

For whom are you writing ? Consultants, techies, management Internal or external people Trained or untrained staff 03.07.2019

For whom are you writing ? Consultants, techies, management Internal or external people Trained or untrained staff 03.07.2019