Vom Code zur Dokumentation - Teil 01.- Prerequisits und Vorbereitungen

Was erwartet uns?

Zur Erstellung einer Dokumentation gibt es mittlerweile mehrere Tools die sinnvoll, dabei zugleich praktisch, teilweise aber auch zu aufwendig sind. Eines dieser schönen handlichen konstenlosen Tools ist z.B. der Sandcastle-Help-File-Builder (SHFB). Ich werde mich im Moment nur mit den zur Zeit kostenlosen Möglichkeiten beschäftigen, da diese sofort und für jeden Einsatzbereit zur Verfügung stehen. Der SHBF ist ein GUI für Sandcastle. Sandcastle wiederum ist das Tool, an dem Microsoft zur Zeit arbeitet um die automatische Generierung der Dokumentation zu erleichtern. Im Moment und schon seit langer Zeit immer wieder als CTP erhältlich (aktuell Januar 2008), dennoch schon sehr gereift und stabil einsetzbar. So etwas gibt es nicht erst seit gestern. Unter Java war dies mit der JavaDoc-Syntax und unzähligen Tools schon vor langem möglich. In der C++ Welt gibt es auch einige - auch OpenSource z.B. doxygen. Nun gut, genug über den Tellerrand geschaut. Also Microsoft verwendet dieses Programm selbst um die Dokumentationen zu erstellen. Die neuere Onlinedoku der MSDN-Library-Seiten wird z.B. damit erstellt.

Unser Ziel

Wir wollen in ein paar kurzen Schritten erklären was wir benötigen um eine Dokumentation zu erstellen. Wir laden uns die Programme herunter und konfigurieren unsere Arbeitsumgebung. Dabei leite ich Schritt für Schritt die Erstellung einer ersten, rudimentären Dokumentation die uns zeigt, dass es leicht funktioniert.

Inhalt

Lost gehts!

Was ist notwendig um aus meinem Quellcode eine Dokumentation mit Sandcastle zu generieren?

Das waren erst einmal die wichtigen und notwendigen Schritte um eine vorzeigbare Dokumentation des Quellcodes und der Codestruktur vorzulegen.

Was gibt es für Alternativen?

Ebenfalls Opensource und auch auf Sandcastle aufbauend gibt es das Projekt DocProject. Es ist ebenfalls umfangreich und integriert sich im Gegensatz zu SHFB direkt ins Visual-Studio. Die Ergebnisse sind logischerweise ähnlich, da sie ja auf Sandcastle basieren. Meiner Meinung nach kann mit DocProject feiner in die Erstellungen eingegriffen werden. Hier fehlt mir aber noch die praktische Erfahrung. Kommerzielle Angebote für Komplette Hilfe-Dateien (IDE artige Programme) gibt es auch zu genüge. Ein kommerzielles Pendant zu DocProject stellt Document! X von Innovasys dar, dass sich sehr gut ins Visual Studio integriert und einen um viele Funktionen erweiterten Umfang besitzt. Ein kostenloses Tool das bei VS2005 noch mitgeliefert wird ist HelpStudio Lite (der kleine Bruder vom HelpStudio) ebenfalls aus dem Hause Innovasys. Für 2008 muss dieses Separat herunter geladen werden. Wer Geld ausgeben kann und will oder muss (Super mit inbegriffen) findet also auch dazu seine Lösung. Zum Schluss sei noch ein weiteres kommerzielles Tool aus dem Hause ComponentOne genannt: Doc-To-Help 2008 

Was erwartet uns in der Artikelserie

In den nächsten Posts werde ich erklären, was mit den einzelnen Einstellungen gemacht werden kann und wie ich z.B. weitere Dokumente benutze um eigenständige Sitemaps unabhängig von dem Code zu erstellen. Diese sind für Übersichtsseiten und kleine HowTo's  praktisch um sowohl eine User- als auch eine Referenz-Dokumentation zu erhalten.

 
Bei Fragen gerne auf mich zukommen! Im übrigen ist die englische Hilfe zu dem SHFB sehr ausgiebig und vollständig.

Update:

• Aritkel auf neues Format der Serie umgestellt.
• Den Link für Sandcastle aktuallisiert. Mehr Informationen unter diesem Blog-Eintrag von mir.