CARDS+

Tag: Wiki (page 1 of 4)

Softwarearchitekturen dokumentieren und kommunizieren

Mein Fazit: Ziel des Buches ist es, den Leser viele wichtige Informationen und praktischen Beispiele in die Hand zu geben, um die Architektur jedes Software-Produktes angemessen zu beschreiben. arc42 zieht sich als roter Faden durch das Buch. Eine gute Wahl, wie ich finde. Ich musste aber schnell feststellen, dass der Autor wenig auf agile Methoden eingeht. Das ist eigentlich schade. Ich hatte die Hoffnung, dass der Autor den Kreis bei der Dokumentation größer zieht. Den gerade agile Methoden brauchen keine scharfe Trennung in fachliche Anforderungen und technische Dokumentation. Bei den Praxisbeispielen fehlen mir moderne Architekturen. Continue reading

Confluence-Tip Seitentitel mit Präfix

Aus eigener Erfahrung wird ein Gärtner regelmäßig mit der Frage konfrontiert, ob im Seitentitel das Präfix für den Baustein wirklich notwendig ist. Das Präfix ist in erster Linie eine Kennzeichnung, ein Stereotyp. Es zeigt an, welcher Baustein die Grundlage für diese Seite ist, welcher Aspekt in der Seite behandelt wird.

ktip Ein Stereotyp (englisch: stereotype) ist eine Erweiterung vorhandener Modellelemente in der Unified Modeling Language (UML). In der Praxis geben Stereotype vor allem die möglichen Zusammenhänge bei der Verwendung (Verwendungskontext) einer Klasse, einer Beziehung oder eines Paketes an.

Ähnlich wie bei UML-Diagrammen haben wir in einer technischen Dokumentation Modellelemente: Im Wiki sind es Seiten. Seiten bieten für alle gleiche Grundfunktionen, bestehend aus neun Überschriftenebenen, drei Absatzformaten (normal, für Code, für ein Zitat) und kombinierbaren Schriftstilen (fett, kursiv, unterstrichen, durchgestrichen).

Continue reading

Confluence-Tip Seitenhierarchie löschen

Der Hersteller von Confluence scheint offensichtlich anzunehmen, dass Löschen von Seiten mit vielen Unterseiten oder einer Seitenhierarchie mit mehreren Ebenen in der Praxis recht selten vorkommt. Nur so kann ich mir erklären, dass Confluence erst seit kurzer Zeit eine entsprechend erweiterte Standardfunktion bietet.

Ein in der Praxis erprobtes Verfahren für das Löschen von beliebig großen Seitenhierarchien nutzt andere Standardfunktionen von Confluence und schafft Abhilfe, wo die neue Standardfunktion noch nicht verfügbar ist.

Bereiche sind die Methode von Confluence, Inhalte in sinnvolle Einheiten zu organisieren. Das Anlegen eines Bereiches (Space) geht einfach und schnell, erfordert aber besondere Rechte.

Weiterlesen auf atlassian.com

Jeder Bereich (Space) kann in den Formaten XML, HTML oder PDF exportiert werden. Die Durchführung dieser Operation erfordert aber besondere Rechte.

Nur ein XML-Export kann aber später wieder importiert werden.

Weiterlesen auf atlassian.com

Ein Bereich (Space) kann mit allen Inhalten gelöscht werden. Diese Operation ist aber endgültig und erfordert besondere Rechte.

Weiterlesen auf atlassian.com

Bereiche (Spaces), die als XML-Export vorliegen, können wieder importiert werden. Die Durchführung dieser Operation erfordert aber besondere Rechte.

Weiterlesen auf atlassian.com

Eine Seite wird in Confluence verschoben, indem die übergeordnete Seite geändert wird. Anders als beim Löschen einer Seiten werden mit der Seite auch alle Unterseiten verschoben.

Weiterlesen auf atlassian.com

Continue reading

Confluence-Tip Seiten sicher löschen

Eine Produktdokumentation für ein erfolgreiches Software-Produkt wird über eine lange Zeit gepflegt. Hygiene ist darum sehr wichtig. Wie Entwickler toten Code identifizieren und entfernen, so muss jeder Autor darauf achten, Inhalte zu entfernen, die nicht mehr gültig sind. Zur Erhaltung der Qualität der Produktdokumentation muss er manchmal ganze Seiten löschen. Im Bereich der kurzlebigen Projektdokumentation (z.B. Besprechungsprotokolle, Analyseergebnisse, Statusübersichten, Berichte an das Management) passiert es immer wieder, dass Links auf Seiten der Produktdokumentation existieren, die ein Autor löschen will.

Die folgenden Standardfunktionen von Confluence werden zu einem einfachen Workflow für sicheres Löschen kombiniert. Damit kann ein Autor sicher feststellen, dass eine Seite nicht mehr aktiv genutzt wird. Falls es eine Verknüpfung gibt, kann er herausfinden, in welcher anderen Seite sich dieser Link befindet. So kann er andere Autoren informieren, bevor er seine Seite löscht.

Ein Seite kann in Confluence ganz leicht von jedem Nutzer gelöscht werden, der das Recht zum Bearbeiten der Seite hat. Sie werden von Confluence nicht endgültig gelöscht, sondern in den Papierkorb (trash) verschoben. Die Seite ist danach für Nutzer nicht mehr sichtbar. Gelöschte Seiten können aus dem Papierkorb von einem Nutzer wieder hergestellt werden. Das geht nur solange, bis der Papierkorb manuell geleert wird.

Weiterlesen auf atlassian.com

Eine Seite wird in Confluence verschoben, indem die übergeordnete Seite geändert wird. Anders als beim Löschen einer Seiten werden mit der Seite auch alle Unterseiten verschoben.

Weiterlesen auf atlassian.com

Verwaiste Seiten (orphaned pages) sind Seiten ohne übergeordnete Seite. Sie sind in der normalen Ansicht von Confluence für den Nutzer nicht sichtbar.

Weiterlesen auf atlassian.com

Der Zugriff auf Seiten (page restriction) kann in Confluence einfach und schnell beschränkt werden.

Weiterlesen auf atlassian.com

Continue reading

Confluence-Tip Seiteninformationen nutzen

Ein Wiki lebt von der Dynamik in den Inhalten. Leser erwarten von den Autoren, dass Informationen im Wiki optimal aufbereitet sind. Zusammenhänge sind wichtig, gleiches Wissen wird an unterschiedlichen Stellen vermittelt. Die große Gefahr bei einem Wiki ist das Kopieren von Inhalten. Genau wie eine Papierkopie ist eine kopierte Information falsch oder veraltet, sobald sich die originale Information ändert. Confluence bietet darum eine Reihe von Funktionen, mit denen Seiten miteinander verknüpft werden. Aber was noch viel wichtiger ist: Confluence bietet auch eine Funktion, um den Überblick über die Verknüpfungen zu behalten.

Der einfachste Fall einer Verknüpfung (Link) von zwei Seiten in Confluence. Ein Link ist ein farblich hervorgehobener Text. Durch Klick auf den Link wird ein Leser auf die andere Seite geleitet.

Weiterlesen auf atlassian.com

Das Makro “Seiten einschließen” (“Include Page”) ist die elegante Variante einer Verknüpfung zweier Seiten in Confluence. Ohne zusätzlichen Klick sieht ein Leser einen Text oder ein Bild an verschiedenen Stellen. Der Autor muss den Inhalt aber nur an einer einzigen Stelle pflegen.

Weiterlesen auf atlassian.com

Continue reading

Qualität sichtbar machen

In einem Vortrag über Herausforderungen und Ergebnisqualität der Pflege im Gesundheitswesen des 21. Jahrhundert war das Motto «Gutes tun und es gut tun». Die Autorin hat gleich zu Beginn ein paar sehr gute Fragen gestellt, die ich für die Methode CARDS+ und für die Frage der Autoren nach der Qualität einer Produktdokumentation adaptieren konnte:

  1. Wie wissen wir, dass wir es «gut tun»?
  2. Wissen alle Entwickler und Tester im Projekt, dass wir es «gut tun»?
  3. Weiß die Betriebsorganisation, dass wir es «gut tun»?
  4. Wissen die Stakeholder und Nutzer, dass wir es «gut tun»?

Die Antwort bei Punkt 1 ist noch leicht zu beantworten. Im agilen Umfeld, speziell bei Scrum, gibt es die sogenannte «prime directive»:

Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.
Norman L. Kerth

Punkt 1 ist unser Ziel und wir glauben fest daran, dass jeder sein bestes dazu tut. Schaffen wir es, alle Personengruppen als Leser unserer Produktdokumentation zu gewinnen, dann können wir jede Frage mit einem klaren Ja beantworten.

Continue reading

Qualität durch Beschränkung

Agile Entwicklung mit Scrum hat aus gutem Grund Regeln, die alle einzuhalten sind. Scrum ist es nur, wenn die drei Rollen Product-Owner, Scrum-Master und Team besetzt sind, das Team in regelmäßigen Sprints ein Product-Backlog abarbeitet und kontinuierlich Produktinkremente liefert. Jeder Sprint wird gemeinsam geplant (Refinement, Planning). Am Ende jedes Sprints gibt es eine Präsentation der Sprint-Ergebnisse (Review). Nur so funktioniert Scrum. Eine Vereinfachung (z.B. Weekly statt Daily) birgt das Risiko, dass das Vorgehen nicht mehr die gewünschten Ergebnisse liefert. Jede grundsätzliche Veränderung führt dazu, dass die Methode nicht mehr funktioniert. Die Änderung der Sprint-Ziele während des Sprints wird gerne als besonders agil bezeichnet. Mit Scrum hat diese Art der Agilität aber nichts zu tun.

Gleiches gilt auch für CARDS+. Die Struktur des Wiki, die Bausteine und Prinzipien und Praktiken sind aufeinander abgestimmt. Nur im Wiki kann inkrementell dokumentiert werden. Die Bausteine sind so gestaltet, dass Wissen schrittweise erfasst wird, vom Groben ins Feine. Code und Test werden berücksichtigt und definieren die Grenzen der Produktdokumentation.

Continue reading

Qualität ist Kopfsache

Ein ganz wesentliches Ziel der Methode CARDS+ ist die Qualität der Inhalte. Prinzipien und Praktiken der Methode sollen unter anderem Autoren die Pflege einer Produktdokumentation im Wiki so einfach wie möglich machen. Die wohl wichtigsten Leitsätze sind:

  • Erfasse jede Information nur an einer Stelle im Wiki.
  • Erfasse nur jene Information, für die es Leser gibt.
  • Erfasse keine Information im Wiki, die an einer anderen Stelle bereits ausreichend beschrieben wurde.
  • Lass jede Änderung mindestens einmal prüfen.
  • Ignoriere keinen Fehler.

Beachten wir sie nicht, ist es sehr wahrscheinlich, dass Inhalte im Wiki sprichwörtlich verderben. Das Schlimme an den verdorbenen Dokumenten ist, dass wir sie niemals sofort erkennen.

Continue reading

Qualität braucht Kompetenz und Verantwortung

“Code smells”, sagte Kent Beck. Bei übel riechendem Code handelt es sich allgemein um Code, der einer gemeinsamen Vorstellungen von guter und lesbarer Programmierung nicht entspricht. Gleiches gilt auch für Texte einer Produktdokumentation im Wiki. Sie brauchen eine Struktur. Kein Scrum-Team braucht literarisch wertvolle Werke. Texte werden von ihnen genutzt, um ein technisches System zu entwerfen und bauen. Wortwiederholungen sind auf jeden Fall gewünscht, Begriffe werden immer gleich benutzt, Doppeldeutigkeiten vermieden.

Ein Wiki ist ein Werkzeug, mit dem die Dokumentation für ein Software-Produkt schnell und sicher erstellt werden kann. Die Methode CARDS+ stellt sicher, dass diese Dokumentation in hoher Qualität dauerhaft erhalten bleibt. Sowohl Werkzeug als auch Dokumentation müssen gepflegt werden. Ein Gärtner ist eine Person, die dafür Verantwortung übernimmt.

Continue reading

Confluence-Tip Stichworte nutzen

Eine wachsende Menge an Seiten in unserem Wiki führt dazu, dass die Baumstruktur in Confluence unübersichtlich wird. Stichworte, richtig verwendet, sind sie ein sehr leistungsfähiges Mittel, um Seiten im Wiki schnell und sicher zu finden, zusätzlich zur Navigation in der Baumstruktur. Stichworte stellen neben Kommentaren und dem Gefällt-Mir-Status sehr nützliche Zusatzinformationen einer Seite im Wiki dar. Stichworte können praktisch in beliebiger Anzahl verwendet werden.

ktip Atlassian hat den englischen Begriff “label” in den deutschen Begriff “Stichwort” übersetzt. Das ist meiner Meinung nicht ganz optimal. Stichworte sind in der üblichen Definition Teil des Textes oder Titels einer Seite. Schlagworte hingegen sind Zusatzinformationen aus einem kontrollierten Vokabular. Schlagworte müssen aber nicht zwingend im Text oder Titel der Seite vorkommen. Schlagwort trifft daher den Kern der Sache besser.

Continue reading

Olderposts

Copyright © 2018 Impressum Datenschutz

Zum Anfang ↑