CARDS+

Month: May 2015 (page 1 of 2)

Prinzipien und Praktiken

Die Initiative der «clean code developer» für mehr Professionalität in der Softwareentwicklung ist ein von mir persönlich geschätzter Katalog von Prinzipien und Praktiken, die uns zu professionelleren, besseren Entwicklern machen (sollen). Ich behaupte, dass sich diese und viele andere Prinzipien der Entwickler ganz leicht auch auf das Dokumentieren in einem Wiki anwenden lassen. Diese Prinzipien und ihre praktische Umsetzung sind ein wichtiger Teil der Methode CARDS+. Nur auf die bunten Bändern kann ich persönlich verzichten.

Continue reading

Im Zusammenhang mit der Spezifikation von Benutzeroberflächen der Anwendung unterscheiden wir Layouts und Manuals. Beide Artefakte haben das Ziel, die Benutzeroberfläche zu beschreiben.
Layouts sind vorrangig für den Entwickler und beschreiben die “Mechanik” der Benutzeroberfläche. Das Mockup im Layout zeigt die Idee für die Gestaltung.
Aber Layouts ersetzen kein Benutzerhandbuch!

Was sind die Kosten?

Kosten sind in jedem Projekt ein Treiber für Veränderungen. Änderungen an der Software müssen ihre Kosten einsparen, sei es im Betrieb (durch Änderungen in der Architektur), in der Nutzung (Nutzer sind effektiver, wie auch immer das beurteilt wird) oder durch Reduktion von Lizenzgebühren, um nur ein paar Beispiele zu nennen.

09 Was sind die Kosten

Gerade im Zusammenhang mit der Produktdokumentation ist es besonders schwer, die Kosten für das Erstellen und Pflegen “kaufmännnisch” zu rechtfertigen. Es ist quasi unmöglich, eine Ziffer hinter den Wert gut gepflegter Dokumentation zu setzen. Darum ist es umso wichtiger, dass der Aufwand für die Erstellung und Pflege der Produktdokumentation minimiert wird.

Und genau das ist der Ansatz von CARDS+.

Continue reading

Das Verfassen einer technischen Dokumentation erfordert viele Fähigkeiten, die einen guten Entwickler auszeichnen!

Warum brauchen wir eine Icon-Sammlung?

Jedes Software-Produkt mit einer grafischen Benutzeroberfläche verwendet Icons. Ein Icon ist ein Piktogramm, die auf einen Blick und so eindeutig wie möglich eine Funktionen des Systems darstellt. Gerade im Hinblick auf die Akzeptanz durch einen großen Nutzerkreis haben Icons ein einheitliches Erscheinungsbild (englisch: look and feel). Viele Icons fassen wir zu einer Icon-Sammlung zusammen. Es ist die konkrete Umsetzung einer Medienbibliothek für Icon-Dateien.

Continue reading

Der Aufwand für die Pflege einer Dokumentation ist um vieles größer als der Aufwand für die Erstellung.

Warum brauchen wir eine Link-Sammlung?

Ein Wiki egal welchen Herstellers ist immer nur für einen gewissen Teil der Dokumentation geeignet. Selbst unsere Produktdokumentation befindet zur Vermeidung von Redundanzen nicht nur im Wiki.

  • Vertragsrelevante Unterlagen müssen in einem revisionssicheren Dokumentenverwaltungssystem gespeichert werden.
  • Schnittstellenspezifikationen werden von Partnersystemen zur Verfügung gestellt.
  • Unternehmensweite Richtlinien und Vorgaben befindet sich im Intranet.
  • Tutorials und API-Dokumentation befinden sich im Internet.
  • Unterlagen zur Code-Generierung (z.B. ein Meldungskatalog) befinden sich in einem Repositiory.

Eine Link-Sammlung ist immer dann notwendig, wenn eine Produktdokumentation in verschiedenen Versionen inkrementell gepflegt wird (also mindestens die Systembeschreibung der Version in Produktion und die aktuelle Version) und wenn es Dokumente außerhalb des Wiki gibt (z.B. API-Dokumentationen als Teil der Architekturdefinition). Beide Annahmen treffen in der Regel zu.

ktip Für Confluence gibt die Erweiterung (Add-onScroll-Version, mit dem ein ganzer Bereich (Space) versioniert wird.

Continue reading

Produktwissen wird auf effiziente Art und Weise an der Quelle erfasst und jedem im Projekt zugänglich gemacht. Dieser Wissenstransfer ist gerade bei einem langfristig angelegten Projekt lebenswichtig!

Welchen Nutzen bringt es?

Wer schon einmal als Analyst, Entwickler oder Tester in ein Projekt eingestiegen ist, das längere Zeit auf Sparflamme gewartet wurde, weiß den Wert guter Dokumentation schätzen – aber nur, wenn die Qualität gut und der Inhalt glaubwürdig ist. In allen anderen Fällen ist Dokumentation mehr Fluch als Segen.

08 Welchen Nutzen bringt es

Was sind nun die Herausforderungen, was die Probleme beim Erstellen und Pflegen einer Produktdokumentation? Welchen Nutzen bringt es uns, neben den obligatorischen Handbüchern auch eine Systembeschreibung zu erstellen und zu pflegen? Wie hilft uns eine Architekturdefinition?

Continue reading

Olderposts

Copyright © 2018 Impressum Datenschutz

Zum Anfang ↑