Dokumentation / Hilfe zu Modulen

[Ralf Hertsch]

Hallo Leute,

wie Michael in einem anderen Thread richtig bemerkt hat, stellt jeder Modulautor ergänzende Informationen zu seinen Modulen auf die eine oder andere Weise zur Verfügung. Der Grund dafür ist, dass es keine entsprechende Regelung dafür gibt - entprechend schwierig ist es für die Anwender an die gewünschten Informationen zu gelangen. Dazu kommt vielleicht auch noch eine Sprachbarriere. Vielleicht gelingt es uns ja, eine bessere Lösung zu erarbeiten.

Meine Sicht:

Es beginnt damit, dass nach der Installation eines Moduls der Anwender das erste Mal alleine dasteht, wenn er z.B. wissen möchte wie er das Modul konfigurieren soll. Optimal wäre wohl: der Anwender klickt auf einen Link im Modulbackend und landet bei der allgemeinen Dokumentation zu diesem Modul und kommt bei Bedarf von dort aus weiter zu den relevanten Threads.

Realisieren läßt sich das über "Anlaufseite" für jedes einzelne Modul. Diese Seite enthält die Dokumentation oder einen externen Link. Eine solche Anlaufseite hätte noch eine Reihe von weiteren Vorteilen, so könnte Sie z.B. die Versionshistorie und den oder die eigentlichen Downloadlinks enthalten - Probleme wie beim Upgrade des Gästebuch wären dann passé. Eine solche Seite böte außerdem die Möglichkeit eine FAQ einzuführen und zu pflegen.

Was meint ihr dazu?

Gruß
Ralf

[ruebenwurzel]

Hallo,

du sprichst da einen wichtigen und guten Punkt an. Davon ausgehend, dass die meisten WB user keine studierten Informatiker sind    sollte es eine einfache Möglichkeit geben, an die Dokumentation der Module zu kommen. Das ist bisher total unterschiedlich gehandelt. Meine Vorstellungen gehen in folgende Richtung:

IM WB admin, dort wo die Module installiert werden (Erweiterungen) wird eine die unterste Zeile "Details zum Modul" dahingehend umgebaut, dass man über das dropdown direkt zu den Einführungsseiten (Hilfeseiten) für das Modul kommt. Damit kann der User das Modul installieren und sich auf der selben Seite gleich die Informationen (bevor er eine Seite anlegen muss wie bisher) holen wie es funktioniert ....

Wie diese Hilfeseiten aufgebaut sind (einfache einzeilige Erklärung bis zu mehrseitigen Abhandlungen) kann ja dann dem Modulentwickler bleiben.

Denselben Hilfe Link bekommt man dann auch, wenn man eine section mit dem Modul erstellt hat.

Die Hilfeseiten innerhalb des Moduls sollten dann im "languages" Verzeichnis liegen. Ob man sie direkt in die Sprachdateien (EN.php, DE.php ...) einbaut oder besser dort ne helpEN.php, helpDE.php .... sollte diskutiert werden.

Das ganze ist denke ich eine Sache, die man sich für WB 2.8 auf jeden Fall vornehmen muss. Wie auch immer die endgültige Lösung dann sein wird.

Matthias

[Ralf Hertsch]

Hallo Matthias,

IM WB admin, dort wo die Module installiert werden (Erweiterungen) wird eine die unterste Zeile "Details zum Modul" dahingehend umgebaut, dass man über das dropdown direkt zu den Einführungsseiten (Hilfeseiten) für das Modul kommt.

Das ist sicherlich der einfachste Weg: die info.php um einen Hinweis auf die Dokumentation ergänzen. Die info.php sollte dann allerdings sprachabhängig aufgebaut werden was bislang nicht üblich ist (warum eigentlich, frage ich mich gerade selbst???)

Die Hilfeseiten innerhalb des Moduls sollten dann im "languages" Verzeichnis liegen. Ob man sie direkt in die Sprachdateien (EN.php, DE.php ...) einbaut oder besser dort ne helpEN.php, helpDE.php .... sollte diskutiert werden.

Auf keinen Fall direkt in die Sprachdateien, das würde diese unnötig aufblasen. Und auf keinen Fall in das /languages Verzeichnis - stell dir vor, der Autor und/oder die Übersetzer möchten Grafiken einbinden, die lägen dann alle in diesem Verzeichnis rum...

Wie wäre es mit einem Verzeichnis /help das Unterverzeichnisse für die jeweilige Sprache enthält, also z.B. /help/DE/ oder /help/EN/ und die Hilfedatei selbst heißt immer help.php?

Das ganze ist denke ich eine Sache, die man sich für WB 2.8 auf jeden Fall vornehmen muss. Wie auch immer die endgültige Lösung dann sein wird.

Das können wir einführen, sobald wir uns einig sind und braucht nicht warten bis WB 2.8. Es wird ohnehin einige Zeit dauern bis alle Module umgestellt sind.


Gruß
Ralf

[doc]

Hallo Ralf,

ab WB 2.7 ist die info.php sprachabhängig, die Module werden nach und nach upgedatet. Die in WB 2.7 vorinstallierten Module können das schon.

Nach dem Release von WB 2.7 wollen wir die Addons Seite (Templates/Module) überarbeiten. Wenn Du Lust und Zeit hast daran mitzuarbeiten, bitte melden.

Gruss Christian

[Ralf Hertsch]

Hallo Christian,

ab WB 2.7 ist die info.php sprachabhängig, die Module werden nach und nach upgedatet. Die in WB 2.7 vorinstallierten Module können das schon.

  Jetzt habe ich aber nicht schlecht aus der Wäsche geschaut. Warum werden denn die Sprachdateien nicht wie sonst eingebunden - Englisch ist nach wie vor hartcodiert? Das ist bei der Übersetzung schon sehr ungünstig, die wenigsten Übersetzer werden wissen, dass Sie $module_description zusätzlich aus der info.php einfügen und übersetzen müssen (schließlich ist die Ausgangsdatei für die Übersetzung die EN.php und in der ist $module_description erst gar nicht enthalten). Außerdem verhindert diese Lösung das Einfügen eines Sprachabhängigen Links auf die Hilfedatei (oder der Modulautor müsste den "Standard" direkt umbiegen).

Auch auf das Risiko mir den Vorwurf anzuhören "Du hättest ja mitarbeiten können" (es ging nun mal leider zeitlich nicht): Ich verstehe das nicht? Warum verwendet WB nicht die selbst gesetzten WB Standards? Warum schon wieder irgendwas Gestricktes, dass überhaupt nicht transparent ist? 

Nach dem Release von WB 2.7 wollen wir die Addons Seite (Templates/Module) überarbeiten. Wenn Du Lust und Zeit hast daran mitzuarbeiten, bitte melden.

Ganz laut und deutlich: Ja ich will.

Immer noch leicht irritiert und ratlos vor mich hinbrabbelnd...

Ralf

[ruebenwurzel]

Hallo,

Wie wäre es mit einem Verzeichnis /help das Unterverzeichnisse für die jeweilige Sprache enthält, also z.B. /help/DE/ oder /help/EN/ und die Hilfedatei selbst heißt immer help.php?

Das ist ein guter Vorschlag. Ein Help Ordner und dadrin eine help.php als ausgangspunkt für die Hilfe. Ob man sich dann auf die help.php beschränkt oder von dieser auf andere Hilfeseiten (denke auch an mehrere Unterseiten mit Bildern getrennt nach frontend und backend und das ganze mehrsprachig) sollte dann dem Modulentwickler überlassen werden.

$module_description

War mal nur dafür gedacht im Backend die Beschreibung auch in anderen Sprachen zu ermöglichen. Da das ja aber nicht in allen Modulen schon umgesetzt ist muss der default Wert aus der info.php zunächst bleiben. Da der in Englisch ist scheint derselbe Eintrag in der EN.php zunächst blödsinnig, aber genau vor dem Hintergrund, dass er beim Übersetzen dann vergessen wird, sollte er eigentlich drinstehen.

Ganz laut und deutlich: Ja ich will.

Super, das find ich doch mal ne Aussage. Denke wir werden dir die entsprechenden Zugangsdaten und Berechtigungen sobald als möglich zukommen lassen. Wir sind dankbar für jeden, der aktiv mitarbeitet, und da du noch dazu qualitativ richtig gutes Zeugs lieferst freut es mich doppelt dich mit ihm Boot zu haben.

Matthias

[Ralf Hertsch]

Hallo Matthias,

Das ist ein guter Vorschlag. Ein Help Ordner und dadrin eine help.php als ausgangspunkt für die Hilfe. Ob man sich dann auf die help.php beschränkt oder von dieser auf andere Hilfeseiten (denke auch an mehrere Unterseiten mit Bildern getrennt nach frontend und backend und das ganze mehrsprachig) sollte dann dem Modulentwickler überlassen werden.

Genau, dann kann er tun oder lassen, auf eine wenigstens minimale help.php sollten wir allerdings bestehen...

War mal nur dafür gedacht im Backend die Beschreibung auch in anderen Sprachen zu ermöglichen. Da das ja aber nicht in allen Modulen schon umgesetzt ist muss der default Wert aus der info.php zunächst bleiben. Da der in Englisch ist scheint derselbe Eintrag in der EN.php zunächst blödsinnig, aber genau vor dem Hintergrund, dass er beim Übersetzen dann vergessen wird, sollte er eigentlich drinstehen.

Ich habe mir das mal genauer angeschaut und verstehe jetzt wieso die Lösung für WB 2.7 so aussieht. Die ganzen Probleme bestünden nicht, wenn die detail.php einfach die info.php ausliest und nicht den Umweg über die Datenbank geht (warum das so ist verstehe ich wiederum nicht, aber was soll's). In diesem Fall läßt sich mit der info.php einfach so verfahren wie mit allen anderen Dateien, die Sprachdateien einbinden und fertig ist der Lack.

Wär' kein großes Ding das noch in WB 2.7 einzupflegen...

Wir sind dankbar für jeden, der aktiv mitarbeitet, und da du noch dazu qualitativ richtig gutes Zeugs lieferst freut es mich doppelt dich mit ihm Boot zu haben.

Danke, bin gerne dabei 

Ralf

[Waldschwein]

Hallo Ralf!

Ich weiß, dass es vielleicht ein bissl arg ist, dass ich jetzt meine Sicht der Dinge (und auch bisher ja leider meinerseits versandeten (Nicht-)Anstrengungen) darlege, aber gut, warum sollte man immer alles im goldenen Käfig behalten.

Daher jetzt als kleine Einstimmung ein Abriss über meine ganz persönliche Erfahrung mit dem Thema:
Ende letzten Jahres war die Euphorie groß, endlich den Addonbereich anzugehen, und etwas zu machen. Sofort gab es aber drei Lager: Die einen wollten lediglich mehr Informationen, die anderen (dazu gehörte und gehöre ich persönlich) eine gewisse Automatisierung des Addonprozesses mit neuer Gestaltung und andere gleich eine ganze Plattform ohne bisheriges (sprich: ohne Foreneinsatz).
Soweit so gut, (im Nachhinein völlig überstürzt) sollte das ganze unter einen Hut gebracht werden, hab mich mit meinen Nichtprogrammier-Kenntnissen vorne drangestellt und gehofft, dass die teilweise schon fertigen Vorschläge, die schon über ein Jahr ungenutzt herumliegen und die Euphorie der Beteiligten genau der richtige Zeitpunkt wäre, jetzt auf Worte Taten folgen zu lassen.
Als nächstes kam dann eben von mir folgender Vorschlag, den ich persönlich - ohne Hinblick jetzt wer es und ob überhaupt jemand macht, aber man darf ja träumen - nach wie vor für "das Beste" halte.
Da war schon natürlich das erste Problem da: XML. Ich persönlich kenne dieses XML-Schema als Laie als etwas absolut einfaches, das - wenn es vorgegeben ist - selbst jemand durchblickt, der noch nie groß sich mit Programmierung beschäftigt hat. Nur hat das die Beteiligten gespalten, in Befürworter, "egal" und "nur über meine Leiche".
Tja, auch letzte verzweifelte Rettungsversuche dann haben die jetzt zum Stillstand gekommene Motivation nicht mehr anfachen können, irgendwie war schlicht die Luft raus. Dann eben ein letzter Versuch unternommen, ohne XML, in vereinfachter Form, einen externen einbezogen (weil ich einfach nicht die Kenntnis und wohl auch nicht die Begeisterung fürs Programmieren habe, Christians Bedenken haben sich halt doch bestätigt), dem wohl nicht richtig gesagt was genau jetzt ich erwarte, und seitdem schlummern (zumindest was ich weiß) die Vorschläge und Scripte wieder stillvergnügt.

So, soviel zu diesem Thema, wollte es einfach mal gesagt haben, bitte nicht böse sein.

Also, dann einmal zu den eigentlichen Fragen, was in meinen Augen jetzt getan werden sollte, um den Benutzer (nicht wie in obigem Schema der Entwickler) das Leben zu erleichtern:

• Ein extra Unterforum unter Module, wo automatisch / vom Modulteam freigegebene Module einen einzigen, offiziellen, englischsprachigen (wen sein soll auch Deutsch) Thread bekommen.
• Alle wichtigen Informationen, Changelog(link), etc. sollten alle im ersten/zweiten Beitrag des jeweiligen Threads hineingeschrieben werden. Nicht jeder hat eine Webseite, wenn, umso besser. Aber ich persönlich finde die Methode, bei einem neuen Release einfach einen Beitrag im jeweiligen Thread hineinzuschreiben auf Dauer schlicht unübersichtlich, vor allem wenn man einmal eine zweistellige Seitenanzahl erreicht hat.
• Auf Dauer eventuell einen Gedanken daran verschwenden, die Mehrsprachigkeit auf wb2.org aufzugeben und stattdessen auf lokalisierte Seiten zu setzen. Das falsch gemacht kann die Gemeinde und wohl auch das Projekt zum Ende bringen, das gut gemacht erreicht denke ich deutlich mehr positives als negatives. Aber kein Muss.
• Der Addonbereich sollte überarbeitet werden, dazu gibt es schon vorgefertigt gute Ansätze. Wichtig ist: Nicht den Benutzer überfrachten, sondern ihm das Leben erleichtern.
• Eine durchsichtige Methode zu erstellen, wann/warum/wozu ein Modul aufgenommen wird. Ich finde nach wie vor die "just PM us" für viel zu umständlich, siehe mein Vorschlag zur Automatisierung oben.
• Eine "coding guideline" zu entwerfen, was der Entwickler tun muss. Speziell: Richtig gepacktes .zip, readme, Lizenz, Unterstützung von Mehrsprachigkeit, Vermeidung von Hardcoding, XSS-Check, usw. usf.
• Die Templates natürlich genauso behandeln, ebenso die (in meinen Augen leider bissl stiefmütterlich behandelten) CodeSnippets.

Wie gesagt, ist die "wäre super toll wenn kommen würde, aber ich weiß schon dass es sowieso nicht geht" Liste von mir.
Ich will jetzt nicht treu dem Motto handeln "Feed the trolls", soll einfach nur meine bisherige "Erfahrung" und Auseinandersetzung mit dem Thema darstellen.

Gruß Michael

[ruebenwurzel]

Hallo Michael,

hab ich was falsch verstanden, oder sollte es bei der Anfrage von Ralf nicht um die Hilfe für Wb user im WB backend gehen? die von dir angesprochenen Punkte beziehen sich allesamt auf die zu überarbeitenden Hilfe und Addonsseiten auf wb.org. Das ist ein völlig anderes Thema, will also sagen, meinst du nicht, dass das ein bisserl offtopic hier ist?

Matthias

[Ralf Hertsch]

Hallo Michael,

die Idee zu diesem Thread war mehr die Frage nach der Dokumentation/Hilfe für die Module und weniger die Strukturierung des Addons Bereich. Da das Thema trotzdem wichtig ist: vielleicht läßt sich dein Posting und diese Antwort in einen neuen Thread hieven?

Ich kann mir gut vorstellen, dass das frustrierend war - ich kann mir vorstellen, dass dein Vorschlag alle erschlagen hat und einfach zu perfekt war 

Ich finde die Idee mit XML gar nicht schlecht, denke aber, erst sollte eine Struktur bestehen die sich in der Praxis bewährt hat und danach kann man sie automatisieren um allen das Leben zu erleichtern. Ich würde auch die zwischenmenschliche Komponente nicht unterschätzen: dafür, dass ich mich bei WB festgebissen habe, war entscheidend, dass mir Christian entgegenkam und mir den Weg geebnet hat.

Deshalb sollten wir m.E., wenn wir über die Strukturierung des Addons Bereich nachdenken, auch laut über Patenschaften für neue Autoren nachdenken. In den Bereich Förderung/Motivation fällt m.E. auch, dass der Topf "unsupported and unoffical" förmlich überquillt und wir uns fragen sollten, warum dort so viele gute aber nur halbfertige Module schlummern und wie wir das ändern können ...

Ansonsten scheint unsere Sicht ähnlich aber nicht gleich zu sein 

Ich plädiere auch ganz stark für eine zentrale Anlaufstelle für jedes Modul. Denke dabei aber weniger an ein extra Unterforum sondern eher an eine einzelne Seite ("Homepage"). Praktisch stelle ich mir das so vor: die Addons-Liste enthält wie bisher die Kurzbeschreibung sowie die Versionsnummer. Anstatt dem bisherigen Downloadlink verlinkt die Liste mit der "Homepage" des Moduls auf websitebaker2.org. Auf dieser Seite befindet sich (sprachabhängig) die Versionshistorie, eine ausführliche Beschreibung, ein Link auf die Hilfedatei/Dokumentation sowie der oder die Downloadlinks. Die bisherige Praxis, Fragen zu Modulen in dem Thread zu stellen, der dem Modul zugeordnet ist, finde ich nicht schlecht.

Damit hätten wir in eine zentrale Anlaufseite für jedes Modul. Pflege und Wartung durch das Addons-Team und/oder den Modulautoren.

Sehr wichtig sind die von dir angesprochenen Coding Guidelines, ergänzt durch eine Patenschaft, es fehlen Guidelines für das Betatesting, vielleicht auch ein Testingteam (es gibt hier einige User die Spaß am Testen haben und vielleicht nur ein wenig Anleitung brauchen um qualifizierte Testberichte zu liefern!!!).

Unterstützung von Mehrsprachigkeit ist ein prima Sache, aber hier fehlt bislang jede Unterstützung, so gibt es sicher einige Modulautoren die an der EN.php scheitern und deren Module deshalb irgenwo schlummern...

Auf Dauer eventuell einen Gedanken daran verschwenden, die Mehrsprachigkeit auf wb2.org aufzugeben und stattdessen auf lokalisierte Seiten zu setzen. Das falsch gemacht kann die Gemeinde und wohl auch das Projekt zum Ende bringen, das gut gemacht erreicht denke ich deutlich mehr positives als negatives. Aber kein Muss.

Ich könnte mir das sehr gut vorstellen, für die reinen Anwender wäre das glaube ich echter Gewinn und würde die Community weiter stärken. Für die Programmierer macht's glaube ich keinen großen Unterschied (wobei die deutsche Community deutlich aktiver ist als die englische!!!).

So weit erst einmal...

Gruß
Ralf

[Ralf Hertsch]

Hallo Leute,

ich habe in der neuen Version des Feedback Module 0.27 mal eine sprachabhängige Hilfedatei eingebaut. Die Struktur ist recht einfach: es gibt ein Unterverzeichnis /help in dem sich weitere Unterverzeichnisse für die jeweilige Sprache befinden, in diesem Fall /DE und /EN. Die eigentliche Hilfedatei heißt help.php.

Der Aufruf erfolgt im Backend über den Button Hilfe analog der Einbindung von Sprachdateien:

Code: [Select]

if (file_exists(WB_PATH.'/modules/feedback/help/'.LANGUAGE.'/help.php')) {
  include(WB_PATH.'/modules/feedback/help/'.LANGUAGE.'/help.php');  }
else {
  include(WB_PATH.'/modules/feedback/help/EN/help.php');  }
Ich finde die Lösung nicht schlecht: sie ist einfach, logisch aufgebaut und sie läßt dem Programmierer alle Freiheiten die Hilfedatei zu gestalten wie er möchte.

Gruß
Ralf