Jeff Atwood hat etwas zum Thema "Technische Dokumentation" gefunden: How to Write Technical Documentation

Welcome to the world of technical documentation!

The situation you are in is no different from any other tech writer. The technical writing process:

   1. Ask engineer how the damn thing works.
   2. Deafing silence.
   3. Crickets.
   4. Tumbleweed.
   5. Just start writing something. Anything.
   6. Give this something to the engineer.
   7. Watch engineer become quite upset at how badly you've missed the point of everything.
   8. As the engineer berates you, in between insults he will also throw off nuggets of technical information.
   9. Collect these nuggets, as they are the only reliable technical information you will receive.
  10. Try like hell to weave together this information into something enlightening and technically accurate.
  11. Go to step 6.

Ok, you're not the doc writing type. That's okay, neither am I. However, people are already working to make this better, and I will continue to do so.

Das hat natürlich mit der Wirklichkeit gar nichts zu tun!
;)

Ja macht denn der gar nichts anderes mehr? Immer nur dem Scott Hanselman alles nachmachen?
Tja, wenn einer soviel zu schreiben hat, dann liest man mal besser mit.

Inzwischen ist sie ja berühmt, die Liste mit Windows Tools für und Entwickler und erfahrene Anwender: Scott Hanselman's 2006 Ultimate Developer and Power Users Tool List for Windows

Und wie immer gibt es eine Menge an wirklich nützlichen Helfern. Viele davon habe ich schon mal ausprobiert. Einige sind auch installiert geblieben. Auch diesmal sind ein paar Neuigkeiten dabei, die sich in der nächsten Zeit bewähren dürfen. Jeder hat eine andere Arbeitsweise und braucht dabei andere Unterstützung.

Unter anderem sind diese Utilities auf meiner Platte gelandet:
Notepad++ Bisher war Notepad2 im Einsatz, aber Notepad++ wird aktiver weiterentwickelt.
WinSnap Wieder ein Screenshot Utility. Vielleicht ist das einfach genug für mich :)

Es bleibt die immer wieder gleiche Frage: Woher nimmt man nur die Zeit, das alles zu testen? Für jedes gute Tool in der Liste gibt es ja auch einige weniger gute. Nach eigenen Aussagen probiert Scott davon auch viele aus. Mir fehlt schon die Zeit, alles aus dieser Liste genauer anzusehen. Aber wenn man schön am Ball bleibt, hat man ein schönes Arsenal an nützlichen Werkzeugen.

Stark verdichtete gute Informationen gibt es immer bei Scott Hanselman und seinem Podcast Hanselminutes.

Die neueste Episode Hanselminutes Podcast 30 - Outlook Add-Ins and Personal Productivity Enhancers ist diese Woche erschienen. Natürlich wird unser kleines Outlook Tool nicht erwähnt :). Dabei ist unser Konzept zum Zugriff auf verschiedene Folder mit weniger Tasten als bei Speedfiler möglich. Dafür muss man sich lediglich die Abkürzungen einmal definieren. Außerdem sind wir billiger.

"Zero Inbox Messages" ist ein schöner Zustand. Kein Schaudern mehr, wenn sich Outlook öffnet.
Meine Inbox ist jetzt seit Wochen "leer". Mein Outlook schreit nicht mehr bei jeder eingehenden Nachricht. Es bleibt mehr Zeit für wichtigere Dinge.

Das Add-In OutlookMoveTo ist bei uns jetzt seit einiger Zeit im Einsatz. Ein paar kleine Verbesserung hat es erfahren und der Setup scheint inzwischen zu funktionieren.
Für mich ist es aber noch keine Software, die man ernsthaft verkaufen kann. Sicher wird es jemanden geben, der bereit wäre dafür Geld zu zahlen. Der Aufwand, eine Software wirklich verkaufsfertig zu machen, ist aber nicht zu unterschätzen.
Als über dieses Blog jetzt eine Anfrage bezüglich dem Erwerb der Software kam, haben wir uns entschlossen, den jetzigen Stand einfach per E-Mail zu versenden.
Folgende Rückmeldung ist dann schon sehr nett. Nochmals Danke dafür:

Ich habe OutlookMoveTo erfolgreich (mit Ihrer freundlichen Hilfe) installiert und es funktioniert hervorragend. Mittlerweile ist das Tool zu einem unverzichtbaren Helfer geworden und es rangiert mit an der Spitze der Tools, die ich täglich verwende. Wo früher eine volle und unaufgeräumte Inbox zu sehen war, so sieht man jetzt Ordnung. Sie sehen - ich bin wirklich begeistert; zumal ich bis dato auch keinen Fehler feststellen konnte.

Wer über dieses Blog Kontakt mit mir aufnimmt, der wird diese Tool sicher auch bekommen.

Natürlich mit dem üblichen Vorbehalten:

• Benutzung auf eigenes Risiko
• Support von uns ist freiwillig
• Keine Weitergabe der Software

 

Update: OutlookMoveTo für Outlook 2007

Ich habe ein kleines Add-In für Outlook geschrieben, um möglichst schnell und einfach Outlook Objekte in definierte Ordner zu verschieben. Getauft habe ich dieses Add-In "OutlookMoveTo". Die Motivation für dieses Tool ist in meinem vorherigen Eintrag Outlook - Posteingang aufräumen nachzulesen.
Nach der Installation erhält man einen zusätzlichen Button in der Symbolleiste von Outlook:



Durch einen Klick auf diesen Button oder der Tastaturabkürzung "Alt + M" öffnet sich der Auswahl-Dialog von OutlookMoveTo:



Bevor man mit OutlookMoveTo arbeiten kann müssen die Zielordner definiert werden. Dazu navigiert man in der Ordnerliste von Outlook an die gewünschte Stelle und öffnet OutlookMoveTo. Durch einen Klick auf "Add" wird der Edit-Dialog mit dem aktuellen Ordner als "Path" geöffnet.



"Shortcut" ist die gewünschte Tastaturabkürzung für diesen Ordner. Diese Abkürzungen sollten sich aus dem Zielordner ableiten lassen. Z.B: Rechnungen Kunde A -> "ra", Auftrag Kunde B -> "ab".
"Name" ist der erklärende Name des Ordners und dient als Stütze, solange die Abkürzungen noch nicht verinnerlicht sind.
"Path" ist der interne Pfad den Outlook für diesen Ordner verwendet. Diesen Wert sollte man nicht normalerweise nicht editieren.
Mit "Ok" wird der neue Ordner gespeichert.
Über "Edit" vom Auswahl-Dialog lassen sich diese Angaben jederzeit ändern.
Diese Liste wird automatisch in den lokalen Benutzerdaten gespeichert.

Und schließlich das eigentliche Verschieben der Outlook-Objekte: Einfach die zu verschiebenden Objekte markieren und OutlookMoveTo öffnen.



Der Cursor steht im "Shortcut" Textfeld. Nach jedem Tastendruck springt die Tabelle an die passende Stelle. Noch kurz "Enter" gedrückt und alle markierten Outlook Objekte werden in den ausgewählten Ordner verschoben. In diesem Beispiel sind insgesamt folgende Tasten gedrückt worden: "Alt + M" "r" "a" "Enter"

Für wenige Ordner und eine flache Hierarchie ist das sicher zuviel Aufwand. Aber bei der unserer Strukturtiefe ist diese Vorgehensweise deutlich effizienter.

Outlook Add-In - Jetzt hier erhaeltlich

OutlookMoveTo für Outlook 2007

Das papierlose Büro hätte es ja schon vor langer Zeit geben sollen. Noch ist es nicht soweit. Aber dennoch ist sehr viel Kommunikation heute elektronisch. Bei uns ist der Exchange Server zusammen mit Outlook als Client die zentrale Plattform.

Jeder Benutzer hat seinen eigenen Posteingang. Eingehende Faxe werden automatisch in einem öffentlichen Ordner abgelegt. Dann gibt es weitere öffentliche Ordner für generische E-Mails, die an unsere öffentlichen Adressen gesendet werden.

Der Posteingang sollte aber nicht zur Sammelstelle bearbeiteter und unbearbeiteter Dokumente verkommen. Mittlerweile ist die Suche nach E-Mails sehr einfach und effizient geworden. Diverse Desktop-Suchmaschinen machen das möglich. Auch Outlook selbst erlaubt eine Suche. Für eingehende geschäftliche Dokumente sollte es dazu aber nach meiner Meinung nicht kommen. Das gehört klassisch sortiert und abgelegt. Spätestens bei der Archivierung dieser Daten geht es eigentlich nicht mehr anders.

Somit müssen eingehende Dokumente im Laufe der Bearbeitung verschoben werden. Der nahe liegende Weg, per Drag & Drop die Dokumente in der Ordnerliste zu verschieben, wird bei vielen verschachtelten Ebenen zur nervigen Übung. Wer zügig arbeiten will, ist mit der Tastatur immer schneller als mit der Maus.

So entstand die Anforderung, per Tastaturabkürzung Objekte innerhalb von Outlook verschieben zu können. Dabei soll jedem Zielordner eine Tastaturabkürzung zugeordnet werden können.

In einem der nächsten Einträge gibt es mehr zur Realisierung zu lesen. Soviel vorab: Mit Visual Studio 2005 (VSTO) habe ich ein Outlook-Add-In gebastelt. Dieses Add-In ist seit einigen Tagen im Einsatz und funktioniert sehr gut. Ein paar Eindrücke von dieser Technologie werde ich noch dokumentieren und das Ergebnis als kostenlosen Download zur Verfügung stellen.

OutlookMoveTo für Outlook 2007

SVG ist die Abkürzung von Scalable Vector Graphics. Dabei handelt es sich um ein W3C Spezifikation die in XML interaktive und animierbare Vektorgraphiken definiert. Innerhalb einer SVG Graphik kann mit Javascript richtig schön programmiert werden.
Wir haben SVG verwendet, um in unserem SQLCat Bilder stufenlos zu vergrößern. Es erscheint ein Übersichtsbild mit dem der sichtbare Ausschnitt verschoben werden kann. Aktive Flächen werden eingezeichnet. Tooltips werden dargestellt. Der Klick auf eine aktive Fläche führt zu einer Navigation im Katalog.

Als wir uns für dieses Format entschieden hatten, war der beste SVG Viewer von Adobe (ASV). Aktuell war die Version 3 und bei einer damaligen Acrobat Reader Installation wurde zusätzlich dieser Adobe SVG Viewer installiert. Der dominierende Browser war der Internet Explorer und ASV das dazu passende Plugin.

Natürlich lief nicht alles rund. Um einige Unzulänglichkeiten des Viewers mussten wir herumbasteln. Manches funktioniert immer noch nicht wie wir uns das dachten. Wie immer bei der Software Entwicklung hofft man natürlich auch auf das nächste Update. Typischerweise werden dann Bugs beseitigt und neue Features implementiert.

ASV Version 3 erschien 11/2001, zumindest sagt das das Adobe Archiv. Es gibt dann noch die Versionen 3.01, 3.02 und 3.03. Letztere ist immer noch die aktuelle Version. Immerhin von 05/2005. Die neuen Versionen sind aber offensichtlich nur Sicherheitsupdates. Von neuen Funktionen oder beseitigten funktionellen Fehlern keine Spur.

Für die ganz mutigen Entwickler gibt es von Adobe noch eine Preview auf die kommende Technologie. Die Technologie von morgen! Spektakulär, die Preview von Adobe Viewer Version 6! Natürlich haben wir uns auch daran versucht. Tatsächlich ist diese Version deutlich schneller und insgesamt besser als die Version 3. Aber das kann man keinem Kunden empfehlen. Ist ja eine Pre-Release, also abwarten und testen.

Wer jetzt genau hingesehen hat, dem ist auf der Download Seite für ASV 6 aufgefallen, dass wir jetzt seit fast 3 Jahren warten. 07/2003 steht da als Release Date. Zappelt es noch?

Inzwischen Unterstützt Firefox 1.5 SVG einfach so, natürlich funktioniert alles anders als beim Adobe Viewer. Aber wen man Google als Indikator nimmt, dann stellt man fest, dass die Kombination IE + ASV dort nicht mehr interessant ist. Deren Web Authoring Statistics werden damit nicht dargestellt: "We recommend Firefox 1.5".

Stirb langsam?  Eher mausetot!

Bisher hatte ich noch nicht mit den Vorabversionen vom IE 7 gespielt. Heute meldet Golem, dass die Rendering Engine keine wesentlichen Veränderungen mehr erfahren soll (Aktualisierte Vorabversion des Internet Explorer 7). Also die neueste Beta 2 installiert und mal auf die eigenen Webauftritte gestürmt.

Hat alles direkt wie erwartet funktioniert. Auch unsere dynamischen SQLCat Seiten werden problemlos dargestellt.
Wenn alles in der normalen Ansicht passt, dann mal die Font-Größe verändern. Am schnellsten geht das ja, indem man bei gedrückter Strg-Taste das Mausrad dreht.
Hui! Was passiert da? Die komplette Webseite inklusive der Bilder wird skaliert. Ein echter Zoom quasi. Nur bei einer unserer Seiten mit vielen Frames (ja macht man nicht mehr, ist aber jetzt so ;) ist das Verhältnis der skalierten Framegrößen zueinander nicht optimal. Das kann man aber sicher noch besser codieren.

Insgesamt gefällt mir das sehr gut. Auch ansonsten fühlt sich der neue Internet Explorer deutlich moderner als sein Vorgänger an.

Das komplette Zoomen einer Seite führt leider beim eingebauten RSS Reader zu unerwünschten Effekten. Zumindest bei kleinen Fenstern wird die eingeblendete Navigation zu groß:

100% Zoom:



150% Zoom:



Details, Details. Natürlich. Alles wird gut. Zwei konkurrierende Browser sind besser, als ein stagnierender Markführer.

Wir vertreiben ein Tool zur Datensicherung: CPTec-Backup. Dieses Programm verwenden wir natürlich auch selbst. Und das ist gut so. Weil wir so leichter erkennen, an welchen Stellen wir nachbessern müssen.

Ein wichtiger Aspekt war für uns, dass wir auf externe USB Festplatten sichern können. Die kann man einfach abstecken und an sicheren Ort bringen. Natürlich verwendet man rotierende Sätze und die nächste Sicherung schreibt auf eine andere Platte. Dabei muss man darauf achten, dass man nicht von einem festen Laufwerksbuchstaben ausgehen kann. Also kann man CPTec-Backup so konfigurieren, dass es die Festplatte an den ersten Zeichen des Datenträgernamens (Volume Name) erkennt. Das funktioniert auch sehr gut. Alle externen Platten für einen Sicherungs-Job beginnen mit dem gleichen Präfix. Problem gelöst.

Im Laufe der Zeit ist uns aber noch eine andere Schwäche an dem Konzept aufgefallen: Externe Platte an einem sicheren Ort sind gut für die bereits gesicherten "alten" Daten. Aber ganz schlecht für neue Daten die zu einem späteren Zeitpunkt gesichert werden sollen. Dazu müssen diese USB-Platten nämlich ihren Weg zurück in die Firma finden. Das konnten wir nicht immer sicherstellen ;).
CPTec-Backup hatte erkannt, dass nicht alle Ziel-Laufwerke für die anstehende Sicherung vorhanden sind, dies gemeldet und die Sicherung abgebrochen. Schade.

Zusätzlich zur Sicherung auf die externe Festplatte sichern wir auch auf eine interne Platte. Jetzt gibt es ein neues Feature in CPTec-Backup, mit dem Ziele als optional markiert werden können. Fehlende optionale Ziele werden beim Start des Backups unter anderem per E-Mail gemeldet und unmittelbar vor dem ersten Zugriff erneut überprüft. Falls die Festplatte dann immer noch fehlt, wird das protokolliert und der Backup fortgesetzt.

Eine ganz aktuelle Demo Version unserer elektronischen Ersatzteilkatalog Software SPCat ist erschienen. Es gibt viele Verbesserungen im Detail, aber der Umstieg auf Visual Foxpro 9 hat die deutlichste Veränderung ermöglicht.
Zur Darstellung von Graphiken mit Links wurde bisher eine selbstentwickelte Visual Basic 6 Komponente verwendet. Das hat sehr gut funktioniert, brachte aber ein paar Einschränkungen mit sich. Unter anderem konnten keine PNG Graphiken dargestellt werden und bei der Installation musste die VB6 Laufzeitumgebung eingerichtet und unser ActiveX-Control (OCX) registriert werden.
Jetzt zeichnen wir die Graphiken direkt mit VFP9 und GDI+. Damit ist unser Katalog nicht mehr auf Visual Basic angewiesen. Das verbessert die Lauffähigkeit von CD und vereinfacht die Installation. Auch PNG Graphiken können wir jetzt direkt darstellen.

Die Demo ist als selbststartende CD ausgelegt. Dazu gibt es ein ISO-Image oder den Inhalt der CD als Zip Archiv. Die schnellste Möglichkeit, den Katalog zu testen ist das Zip Archiv zu entpacken und im "cd" Verzeichnis das "intro.exe" zu starten. In dem dann erscheinenden Dialog einfach "Katalog von CD aus starten" wählen.



Wer sich mehr für die technischen Details interessiert, den verweise ich auf einen früheren Blogeintrag dazu: VFP 9: GDI+ und normale Foxpro Controls auf einer Form