thanx and best wishes to U all

I'd like to wish my dear readers a merry X-mas and a happy, healthy, succesful and prosperous new year.

Wanted: Autoren

Die renomierte IT-Fachzeitschrift OBJEKTspektrum (zu dessen Fachbeirat ich seit längerem gehören darf...) sucht qualifizierte thematisch interessante Beiträge für die kommenden Ausgaben. Wenn Sie also zu IT-Themen schon immer mal einen Artikel schreiben wollten - nur zu! Autoreninfo zum OBJEKTspektrumMehr Info gibts hier.

Architekturdokumentation - Wie wenig ist genau richtig?

Peter Hruschka und ich arbeiten mit arc42 ja schon länger daran, Architekturdokumentation effektiver zu gestalten. Einige Aspekte haben wir unter dem Titel "Wie wenig ist genau richtig" mal zusammengefasst - erschienen im aktuellen ObjektSPEKTRUM.

How to slow down your project (DITA bashing)

just in case you need to stall your project, slow down progress and eliminate most of the unwanted agility of your folks: Try out markup documentation. Instead of writing with a word processor or a wiki, make your guys use some strange markup language. DITA (Darwin Information Technology Architecture) is a great example. I stumbled over it in a recent project. My personal estimate is that one needs at least three (3!) times as long to document something than with one of those old-fashioned but simple tools like wiki or a word processor (A few of my comments hold for docbook too...)

Why that? Isn't the whole world calling for more structure, for markup languages?

Might be - but markup documentation suffers from several serious drawbacks:

• You need pretty elaborate tool chains to efficiently produce such documentation. To really work with DITA for example, some ant scripts and a little xslt may seem sufficient. Be assured - in reality it is not. Experience taught me you need at least a DITA-aware XML-editor and some fancy post-processor (like FrameMaker).
  
• You need a build cycle to compile your documenation sources into something visible. That's why smart people invented WYSIWYG editors some years ago - with tremendous success. And now DITA forces me to refrain from these productivity gains?! Agile development is about fast feedback, I heard :-)
  
• You need some type of content management system to enable re-use of documentation chunks. In one of my projects DITA was introduced with the promise of single-source documentation. In reality it turned out that many chapters were written redundantly - due to a lack of content management. If you control vast sources of money, this one poses no problem for you.
• You need to educate your authors. Sounds easy, does it? Please come back from fairy tail country: IT IS REALLY HARD to educate programmers to use anything which slows them down. About hundred different tags, no industry-wide accepted standard on when-to-use-what-tag, do we really need that complexity again?
  
• Forget about copy and past some diagrams into your word-processor: Such quick (and sometimes really productive) actions are impossible in DITA.
• You are working with plaintext format - no multi-user capabilities like "comments" or "change history".

My suggestion: Unless you are producing product documentation for a mass-market, stick to simpler tools. DITA documentation is NOT simple, it is expensive and slow. If you have the money and the time, DITA might be the right choice for you. I heard of books which were produced with docbook - but not many! For good reason - at least a few authors are smart and aware of their limited lifetime.

Licht in der (Service-)Dunkelheit

Es gibt sie noch, die Lichter im Dunkel der vermeintlichen Servicewüste Deutschland. Gutes Beispiel aus meiner Erfahrung ist der Internet-Copyshop Copymobil. Hier antwortet der Chef noch selbst auf Anfragen, und zwar pronto. Schnelle Produktion und Lieferung, unkomplizierte Abwicklung - so stelle ich mir Service vor. Danke Herr Schenkl. (Nein, dies ist keine bezahlte Werbung, sondern persönliche Meinung und Empfehlung!)