Das Auge lernt mit – gute Dokumentationen

Es ist wieder so weit. Phphatesme startet nach der Winterpause ins neue Jahr. Ich bin wunderbar nach 2012 gerutscht und der Urlaub vor Weihnachten und die Feier selbst, waren auch gelungen. Also genügend Gründe wieder mit Energie mit phphatesme zu starten. Ich hoffe ihr freut euch so wie ich es tue.

Damit ich euch (und wahrscheinlich am meisten mich) nicht gleich überfordere hier eine Kleinigkeit, die mir in den letzten Wochen aufgefallen ist. Das Team, in dem ich arbeite produziert Tools, mit denen die übrigen Entwickler arbeiten können. Und es ist unglaublich wie wichtig dabei die Dokumentation ist. Ok, das war klar, aber was mir nicht ganz so klar war, ist, dass Doku auch gut aussehen muss, damit man sie gerne liest. Struktur ist dabei ja obligatorisch. Wir hatten beim aktuellen Projekt mit einer Standard-Wiki-Struktur angefangen. Also plattgekloppt. Kann man machen, sollte man aber nicht. Versucht man so eine lesefreundliche Version zu bauen, hat man oft die A-Karte gezogen. Strukturen gehen verloren.

Zum Glück hat unser Wiki (Confluence) einen besonderen Dokumentations-Modus, mit dem alles schon viel leichter von der Hand geht. Was mir danach aber sehr wichtig war, was die Anpassung des CSS. Man ist es einfach nicht gewohnt auf den großen 22-Zoll-Monitoren von Links nach Rechts zu lesen. Da bekommt man ja ’nen Drehwurm oder besser ’nen Schwenkwurm. Also Breite anpassen, Zeilenabstände (line-height) vergrößern und auf einmal flutscht es. Die Entwickler haben die Änderungen sehr dankbar angenommen. Ich schau mal, ob ich noch eine Vorher-Nachher-Grafik erstellen kann, damit ihr wisst, was ich meine.

Also macht euch nächstes mal einfach ein paar Gedanken darüber, ob das was ihr schreibt nicht nur inhaltlich korrekt ist, sondern auch eine Form hat, mit der man arbeiten möchte. Ach ja, die Symfony2-Struktur und -Optik finde ich sehr gelungen, da haben wir uns dann auch ein wenig dran orientiert.

Was ich ganz vergessen hab: Frohes neues Jahr euch allen.

PS: Das phm|network ist grad kaputt, aber wir kümmern uns baldmöglichst drum.