Documentation 03.07.2019.

Präsentation zum Thema: "Documentation 03.07.2019."—  Präsentation transkript:

1 Documentation

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

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

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

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

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

7 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.

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

9 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.

10 What is a good documentation

11 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 s 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 s threads to the appropriate topics.

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

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

14 Documentation Guidelines

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

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