Facebook
Twitter
Google+
Kommentare
3

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.

Über den Autor

Nils Langner

Nils Langner ist der Gründer von "the web hates me" und auch der Hauptautor. Im wahren Leben leitet er das Qualitätsmanagementteam im Gruner+Jahr-Digitalbereich und ist somit für Seiten wie stern.de, eltern.de und gala.de aus Qualitätssicht verantwortlich. Nils schreibt seit den Anfängen von phphatesme, welches er ebenfalls gegründet hat, nicht nur für diverse Blogs, sondern auch für Fachmagazine, wie das PHP Magazin, die t3n, die c't oder die iX. Nebenbei ist er noch ein gern gesehener Sprecher auf Konferenzen. Herr Langner schreibt die Texte über sich gerne in der dritten Form.
Kommentare

3 Comments

  1. Atlassian hat schon sehr gute Software. Jira will ich auch nicht mehr missen wollen 🙂

    Übrigens, ich habe gehört, dass man Browserfenster auch kleiner als die gesamte Monitorbreite nutzen kann 😛

    Alles Gute im neuen Jahr!

    Reply
  2. Hi frohes neues Jahr,

    @Nils wie und vor allem was dokumentiert ihr im Wiki bzw. in welchem Umfang ?

    Viele Grüße
    Marcus

    Reply

Leave a Comment.

Link erfolgreich vorgeschlagen.

Vielen Dank, dass du einen Link vorgeschlagen hast. Wir werden ihn sobald wie möglich prüfen. Schließen