Hilfeseite direkt verlinken in Addonseite

[phoebusryan]

Wie am Redaxotag besprochen wäre es toll, wenn man in der Addonseite z.B. neben dem Addonnamen ebenfalls ein Fragezeichen hat, welches auf die Hilfeseite verlinkt. Einfach, damit auch wirklich jeder User die Hilfe für ein Addon findet.

[tbaddade]

Würde es gern als Tab sehen aber auf der rechten Seite. Hätte den Vorteil das man ggf. auch eine Unternavi noch zusätzlich anbieten könnte.

help.page-a.php
help.page-b.php

[gharlan]

Markdown-Parser ist nun drin, und das Fragezeichen in der Addonverwaltung zeigt nun die README.md falls keine help.php vorhanden ist.

Ich glaube, in der Addonpage würde ich nichts automatisch machen, um es dem Addonentwickler zu überlassen, ob er die Readme anzeigen will, oder eine ausführlichere Hilfe (eventuell verteilt über mehrere Seiten).

Ich könnte mir stattdessen diese Hilfsmittel vorstellen:

• Zum Einen allgemein die Möglichkeit, Subpages auf der rechten Seite anzeigen zu lassen. Dies scheint jetzt sogar schon zu klappen, siehe unten
• Zum Anderen die Möglichkeit Markdown-Dateien als Subpages einzubinden.

Konkret könnte das dann so in der package.yml aussehen, wenn man die Readme als Tab auf der rechten Seite anzeigen möchte:

page:
    title: Meine Page
    subpages:
        sub1: { title: Sub1 }
        sub2: { title: Sub2 }
        readme:
            title: Hilfe
            itemClass: pull-right
            subPath: README.md

Das subPath-Attribut gibt es schon, aber es müssen bisher PHP-Dateien sein.
Addons sollen Subpages in ihrer Mainpage ja mit dieser Methode einbinden:

rex_be_controller::includeCurrentPageSubPath();

Diese Methode würde dann Markdown-Dateien automatisch parsen.

Nur so als Idee. Es ist natürlich auch nicht allzu viel Aufwand, eine PHP-Datei für die Subpage anzulegen, wo man die Markdown-Datei selbst parst. Daher die Frage, ob das ganze überhaupt notwendig ist.
Aber so könnte man halt sehr einfach die Readme als Subpage einbinden, und zum Beispiel auch die CHANGELOG.md, falls man möchte etc.

Was meint ihr dazu? Noch andere Ideen.

[tbaddade]

Was meint ihr dazu?

Sehr gute Idee 👍

[polarpixel]

Ihr wisst, dass Jan grade ein Konzept für eine Doku-Sektion in einem AddOn entwickelt hat? Aktuell für YForm, soll dann aber auch für andere AddOns nutzbar sein. Er hatte da ein paar Dateibenamungs-Konventionen festgelegt, glaube ich.

[gharlan]

Ihr wisst, dass Jan grade ein Konzept für eine Doku-Sektion in einem AddOn entwickelt hat?

Ja, so im Groben schon. Hab gerade mit Jan gesprochen, das ist aber unabhängig hiervon. Ist halt ein Weg für eine sehr ausführliche Doku, aber unabhängig vom Core.
Er findet den Vorschlag oben gut.

[polarpixel]

OK.

[alxndr-w]

Ich möchte das hier nochmal kurz aufgreifen und folgenden Vorschlag machen:

Vorschlag

• Wenn es keine umfangreiche Doku gibt, könnte man immer auf die README.md zurückgreifen
• Dieser Reiter befindet sich immer rechts
• Die help.php könnte ebenfalls immer die README.md geparst ausgeben.

Beispiel

In der Lösung von @dergel zu YRewrite ist das ja prototypisch umgesetzt. Ich habe das für mein Addon etwas weiterentwickelt und bräuchte noch etwas Unterstützung, wie ich

• Bilder einfügen kann und wie die Struktur im Dateisystem dafür aussehen muss, dass sie in REDAXO und auf Github angezeigt werden.
• die Hilfe ggf. mehrsprachig ausgeben kann (README_EN.md bspw.)
• Sprunganker richtig ausgeben kann.

Vorteile

• Die README.md wird auch in Github-Repos immer richtig angezeigt. Nutzer können so mehr über das Addon erfahren, noch bevor sie es installieren.
• Addon-Entwickler und die Community hätten eine Vorgabe, wie sie Hilfe/Dokus einfach schreiben können
• Die Lösung bleibt kompatibel zur bisherigen help.php bei der Addon-Liste

[alxndr-w]

Es gibt hierzu eine prototypische Umsetzung, die bspw. auch Addon-übergreifend funktionieren würde. Dazu müssten sich Addon-Entwickler an gewisse Standards bei der README.md und mehrsprachigen Seiten halten:

Beispiel:
yakamara/redaxo_yrewrite#225

[gharlan]

Tipp: Für neue Vorschläge neue Issues öffnen, nicht in geschlossenen diskutieren.
Mir war dein Beitrag vom 23.4. zum Beispiel nicht bekannt, ich muss ihn zwar kurz gesehen haben, aber habe ihn scheinbar wieder vergessen. Und wenn du hier jetzt nichts geschrieben hättest, hätte ich ihn nie (wieder) gesehen. Die offenen Issues gucke ich hingegen immer mal wieder durch.

Zur Sache: Muss ich mir mal alles in Ruhe anschauen. Ohne neues Issue kann aber auch passieren, dass ich es wieder vergesse. ;)

[alxndr-w]

@gharlan kann man ja wieder aufmachen, dachte, es wäre einfach thematisch hier richtig.

[gharlan]

@gharlan kann man ja wieder aufmachen, dachte, es wäre einfach thematisch hier richtig.

Mir sind da neue Issues wirklich lieber. Man kann ja alte verlinken, wenn man sich drauf beziehen möchte.
In diesem Issue hatten wir erst mal eine Lösung entwickelt, die umgesetzt, und dann das Issue geschlossen. Das Issue war/ist dabei im Milestone 5.2. Diese Verknüpfung möchte ich zum Beispiel nicht aufheben.
Ich finde es daher sauberer, mit einem Folgewunsch (oder wie man es auch immer nennen mag) in einem neuen Issue zu starten, es dort zu diskutieren, ggf. wieder einem Milestone und/oder Assignee zuweisen, und so weiter.