Werden Sie ein Dokumentations-Ninja

Das Schreiben von Dokumentation nervt! Aber es gibt Möglichkeiten, es einfacher zu machen und vielleicht sogar Spaß! In einem meiner früheren Blogs habe ich erklärt, wie Sie Ihre Dokumentation in Ihre Pull Requests einbetten können und warum Sie das auch tun sollten. In diesem Blog möchte ich etwas näher auf die Syntax eingehen, die Sie verwenden können, um Ihre Dokumentationsseiten in Confluence zu verbessern.

Syntax? Sie meinen Markdown, richtig?

Ja, Markdown ist die Dokumentationssyntax, die Mark verwendet. Es gibt jedoch einige Erweiterungen, die auch im Markdown-Format gültig sind und es Ihnen ermöglichen, die Makros von Confluence zu verwenden.

Verlinkung zu anderen Seiten

Wenn Sie Dokumentation schreiben, haben Sie wahrscheinlich verschiedene Seiten, auf denen unterschiedliche Dinge erklärt werden. Sie können die Bereiche logisch aufteilen und so die Navigation und das Lesen erleichtern. Aber manchmal möchten Sie von einer Seite auf eine andere verlinken. Das Problem ist, dass Sie die URL noch nicht kennen, da es sich um eine Confluence-Seite handelt. Sie könnten die Seite veröffentlichen und den Link nachschlagen, was die Motivation, eine Dokumentation zu schreiben, zunichte macht. Nehmen wir an, wir haben eine Seite wie diese:

# My Confluence Page

My description of the page

Und wir möchten einen Link zu dieser Seite erstellen. Dies können Sie einfach mit der folgenden Syntax tun:

Read this on [My Confluence Page](ac:) or [read](ac:My Confluence Page) the page.

Wie Sie sehen, können Sie auf den Seitentitel selbst verlinken. Oder Sie können ein benutzerdefiniertes Wort wie "lesen" verwenden und auf die Seite verlinken. Wenn Mark die Seite in Confluence hochlädt, werden die Links automatisch aufgelöst.

Verknüpfung mit Jira-Themen

Neben der Verknüpfung mit Seiten werden Sie wahrscheinlich auch auf Jira-Issues verweisen. Sie können jedoch auch auf Jira-Ereignisse verweisen, indem Sie das native Markdown verwenden. Wenn Sie das Jira Referenzmakro verwenden, werden der Typ, der Titel und der Status der Anfrage angezeigt. Dadurch erhält der Leser sofort eine Rückmeldung über den Status. Dazu müssen Sie ein Makro am Anfang Ihrer Markdown-Datei definieren und die Frage als reinen Text angeben. Hier ist ein Beispiel:

<!-- Macro: MYJIRA-d+
     Template: ac:jira:ticket
     Ticket: ${0} →

# My page that contains a Jira ticket reference

See task MYJIRA-123.

In diesem Beispiel ist MYJIRA der Jira-Projektcode. Die Makrodefinition passt auf alles, was mit MYJIRA- beginnt und von einer Reihe von Ziffern gefolgt wird. Sie können die Fragen dann einfach in Ihrer Markdown-Datei erwähnen, und sie werden automatisch in Jira-Makros umgewandelt.

Codeschnipsel in ausklappbaren Makros ausblenden

Besonders wenn Sie Dokumentation schreiben, müssen Sie möglicherweise Teile der Codeschnipsel ausblenden. Ein Beispiel, das ich verwende, sind betriebssystemabhängige Anweisungen. Nehmen wir an, Sie möchten Anweisungen zur Verwendung Ihres Produkts auf der Kommandozeile geben. In diesem Fall könnten Sie Anweisungen für Windows, Linux und MacOS geben. Um dies zu tun, müssen Sie zunächst das Makro definieren. Dann verwenden Sie das Makro, um das zusammenklappbare Snippet zu erstellen.

<!-- Macro: :expand-start:(?s)(.*?):n(.*?)n:expand-end:
     Template: ac:expand
     Title: ${1}
     Body: ${2}  -->
# My page with command line instructions

Before you start, you must ensure you set the environment variable:

:expand-start:Unix:

Unix instructions go here

:expand-end:

:expand-start:Windows:

Windows instructions go here

:expand-end:

Seiteneigenschaften und Statusabzeichen

Das ist mein Favorit! Dies ist eine so leistungsstarke Funktion von Confluence. Für diejenigen unter Ihnen, die mit dieser Funktion nicht vertraut sind, definieren Sie eine Tabelle, die eine Reihe von Schlüsseln und Werten enthält. In dieser Tabelle können Sie zum Beispiel einen Eigentümer und ein Datum angeben. Sie müssen auch eine Beschriftung für die Seite festlegen. Dies ist für die Berichtsseite erforderlich. Die Bezeichnung wird verwendet, um eine Liste der Seiten zu erstellen, die diese Bezeichnung haben. Der Clou ist jedoch, dass Sie auch die Werte der Seiteneigenschaften anzeigen können.

Wie Sie im Screenshot oben sehen können, haben wir drei Seiten. Die übergeordnete Seite enthält den Bericht, und die untergeordneten Seiten sind Projekt 1 und Projekt 2. Es werden jedoch auch das Datum, der Eigentümer und das Statusabzeichen angezeigt. Auf diese Weise können Sie sich einen guten Überblick über die Projekte verschaffen.

Um die Seiteneigenschaften auf der untergeordneten Seite zu erstellen, benötigen Sie die folgende Syntax.

<!-- Parent: Projects -->
<!-- Label: project -->
<!-- Macro: :in-progress:
     Template: ac:status
     Title: In Progress
     Color: Blue -->

# Project 1

<ac:structured-macro ac_name="details" ac:schema-version="1">
    <ac:rich-text-body>
        <table>
            <tbody>
                <tr><th><strong>Status</strong></th><td>:in-progress:</td></tr>
                <tr><th><strong>Owner</strong></th><td>Joris Conijn</td></tr>
                <tr><th><strong>Date</strong></th><td>2025-02-15</td></tr>
            </tbody>
        </table>
    </ac:rich-text-body>
</ac:structured-macro>

Die Markdown-Datei von Project 2 ähnelt der obigen Datei. Allerdings hat die übergeordnete Seite eine andere Definition.

# Projects

<!-- Include: ac:detailssummary
     SortBy: Title
     CQL: 'space = "Projects" and label = "project"' -->

In diesem Beispiel heißt mein Confluence-Bereich Projekte. Die Confluence Query Language (SQL) ruft alle Seiten im Bereich Projekte ab, die die Bezeichnung Projekt tragen. Eine dritte Voraussetzung ist, dass die Seite auch die Seiteneigenschaften definiert haben muss. Wir haben dies für die Projekte 1 und 2 getan, so dass die beiden Projekte in der Tabelle angezeigt werden.

Fazit

Das Schreiben von Dokumentationen muss keine lästige Pflicht sein. Durch den Einsatz von Confluence-Makros in Markdown können Sie Ihre Dokumentation mit dynamischen Links, Jira-Problemreferenzen, ausklappbaren Inhalten und strukturierten Seiteneigenschaften aufwerten. Diese Funktionen machen Ihre Dokumentation interaktiver, einfacher zu pflegen und nützlicher für Ihr Team.

Indem Sie diese Verbesserungen direkt in Ihre Markdown-Dateien einbetten, rationalisieren Sie den Prozess des Schreibens und Aktualisierens von Dokumentationen, verringern die Reibung und verbessern die Akzeptanz. Wenn Sie also das nächste Mal eine Funktion oder einen Prozess dokumentieren, versuchen Sie, diese Techniken zu integrieren. Sie werden feststellen, dass Dokumentation effizient ist und Spaß macht!

Foto von cottonbro studio