Dokumentation Patternanpassung

• Ähnliche Inhalte (Produktbeschreibungen, Komponentenbeschreibungen, Meetingdokumentationen und so weiter) werden mit dem struct plugin verwaltet. Für jeden Inhalts-„typ“ muss ein struct schema entwickelt werden.
  • Inhalte zu einem struct schema können komfortabel in sogenannten struct aggregations tabellarisch ausgegeben werden.
  • Anmerkung: Die Ausgabe in struct aggregations ist der eigentliche Sinn von struct.
• Die Zuordnung einer Wikiseite zu einem struct schema erfolgt über struct assignements. Hierbei werden für jedes struct schema die Namensräume festgelegt, in denen das schema angewendet werden soll.
  • Es ist auch möglich, an Stelle von Namensräumen reguläre Ausdrücke zu verwenden.
  • Normalerweise liegen alle Inhalte desselben schemas in dem selben Unterordner. (Ausnahme siehe unten)
• Wenn man Hierarchien bilden will, bspw Produkt > Feature > Testcase, so ordnet man die Inhalte in einer Namensraum-Hierarchie an
  • In diesem Beispiel liegen Testcases nicht alle in dem selben Unterordner, sondern je nach Feature in einem eigenen Unterordner des Features.
  • Solche Hierarchien sind lebendig, d.h. ändern sich im Laufe der Zeit.
• Ein Entwurfsziel der struct patterns im sprintdoc Projekt ist, flexibel Hierarchien aufbauen zu können, ohne administrative Anpassungen vornehmen zu müssen.
  • Um die Schema Assignements bei jedem neuen Unterorndner nicht permanent nachpflegen zu müssen, arbeitet man dort mit regulären Ausdrücken. Hierzu ist es notwendig, dass alle struct Inhalte bestimmten Konventionen der Namensraumbenennung folgen.
  • Anstelle von Namespace-Templates arbeitet man mit dem Newpage Plugin. Dieses erlaubt das Anlegen einer Seite in einem (Unter)Ordner und kann sogar das Template genannt bekommen, mit dem die neue Seite angelegt wird.
  • Die struct Aggregationen ermöglichen es auch, selektiv nur in Unterordnern Inhalte aufzuzeigen. Der globale Pfad zum aktuellen Dokument wird hierbei nicht benötigt, man kann mit relativen Pfaden arbeiten. Liegen also alle Testcases immer in Unterordnern .:testcase, So kann ein und dieselbe Aggregation an verschiedenen Stellen verwendet werden. Wir nutzen diese Technik, um die Syntax für Aggregationen in sogenannte snippets auszulagern und per include in die Seiten zu integrieren, wo die Aggregationen erscheinen sollen.
  • An Stelle eines längeren Codeblocks für die Aggregation genügt nun eine einzige Zeile, diese Zeilen lassen sich mit dem Plugin scrapbook auch dynamisch in bestehende Seiten einfügen.
  • Wir integrieren in die Snippets zudem den newpage Button. Dieser erscheint somit automatsich unterhalb der Aggregation. Wir denken, dass dies dem typischen Anwendungsfall eines Dokumentators entspricht: Man legt eine Seite dann an, wenn sich in der Liste der Inhalte noch kein entsprechendes Dokument befindet.

1. Erzeugen und zuweisen des Schemas
   1. Anlegen und konfigurieren des Schemas im Adminbereich Struct Schema Editor ⇒ Dokumentation
   2. Anlegen des Assignments (auf welche Namensräume/Seiten soll das Schema angewendet werden?) im Adminbereich Struct Schema Assignments ⇒ Dokumentation für Aggregationen
   3. Aggregationssnippet ⇒ ist ein Include-Code für die Integration einer Aggregation in eine andere Seite inkl. Neu-Anlegen-Feld (für die Standardpatterns in :patterns:snippets:) ⇒ diese „Snippets“ können über das Scrapbook-Plugin eingefügt werden
2. Optional: für Toplevel-Pattern (die andere Pattern aufnehmen können, wie z.B. Projekte oder Produkte) bietet es sich an, Formulare mit dem Bureaucracy-Plugin zu entwickeln, um diese Sub-Pattern bereits bei Anlage des Toplevel-Pattern gleich mit anzulegen

Wie funktioniert das Einfügen von Aggregationssnippets per Scrapbook?

• Benennungen:
  • sollten grundsätzlich auf Englisch erfolgen
  • da zumeist mehrere Pattern zusammen gehören, sollten diese auch entsprechend so sortiert werden, so sind die Standardpattern bspw. alle im Namensraum „patterns“ einsortiert und die Schemata heißen alle name_pattern ⇒ unternehmensspezifische Pattern könnten bspw. in den Namensraum „unternehmensname_pattern“ gelegt werden
  • Schema-Elemente werden in Einzahl benannt, es sei denn sie können mehrere Werte aufnehmen
• Templates:
  • Seitentitel können standardmäßig aus dem Seitennamen übernommen werden (Nutzer muss dann die Seite nicht extra benennen), dazu wird in den Seitentitel folgende Syntax aufgenommen:

    @!!PAGE@

  • Toplevel-Pattern-Templates (siehe z.B. Produkt) können Platzhalter (z.B. @@Meeting|@@) für die Aggregationen aufnehmen. Im Formular (siehe z.B. Neues Produkt) wird dann die Syntax (analog zur Syntax im Aggregationssnippet) als Variable (z.B. Meeting) an das Template übergeben und ersetzt den Variablennamen-Platzhalter im Platzhalter
  • Hilfetexte (wie den obigen) können mittels Include-Plugin und Folded-Plugin eingebunden werden. Die Hilfetexte liegen im Beispiel unter patterns:help:project

  • ++++ Wie funktioniert das Einfügen von Aggregationssnippets per Scrapbook?|
    {{page>patterns:help:project&nofooter&inline}}
    ++++

• Aggregationen sollten folgende Elemente enthalten:
  • Titel zur Beschreibung dessen, was sie darstellen
  • Überschrift ab der inkludiert werden kann (z.B. „Zugehörige irgendwas“)
  • Aggregation selbst entsprechend der Dokumentation
  • wichtig: der Filter filter: %pageid%*~$NS$: fokussiert auf den Namensraum der aufrufenden Seite (bspw. „projektname:start“), die Testcases (siehe unten NEWPAGE) befinden sich unterhalb des Namensraums „projektname“, daher werden nur diese Testcases ausgegeben
  • Anlageformular: {{NEWPAGE>.:testcases#patterns:templates:testcase}}
    • Auf Basis des Templates patterns:templates:testcase wird eine Seite im Namensraum .:testcases unterhalb der aufrufenden Seite erzeugt

  • ====== Testcase Aggragationstemplate ======
    
    ===== Zugehörige Testcases =====
    
    ---- struct table ----
    schema: testcase_pattern
    cols: %pageid%, id, priority, component, tester
    filter: %pageid%*~$NS$:
    dynfilters: 1
    ----
    
    Zur Anlage eines neuen Testcases bitte dessen Namen hier eingeben: 
    {{NEWPAGE>.:testcases#patterns:templates:testcase}}

• Aggregationssnippets:
  • {{page>patterns:aggregations:changerequest#Zugehörige Change Requests&nofooter}}
  • Es wird die Aggregation ab der entsprechenden Überschrift ohne Fußzeile (Originalort etc.) inkludiert
  • Siehe auch Dokumentation des include-Plugins