# [OT] Gentoo Dokumentations Projekte

## pi

Hallo,

Ich denke das sich viele User einen gewessen Erfahrungsschatz mit und durch den Umgang mit GentooLinux angeeignet haben. Oftmals hat man ein Ziel und stolpert unterwegs über irgendwelche Probleme. 

Dieses NowHow liegt verteilt in irgendwelchen install-logs oder aufgeschrieben auf einem Zettel unter tausend anderen irgendwie wichtigen Notizen. Hier stellt sich die Frage ob es nicht wirklich Sinn macht eine Plattform zu schaffen auf der "User für User" Dokumentationen ablegen können. Dies natürlich nicht auf "www.gentoodoku.de" oder was weiss ich wo sondern da wo es hin gehört auf gentoo.de/org.

Hier stellt sich die Frage an unsere Admins ob z.Bsp. ein Wiki einrichtbar wäre und an unsere User wer die Möglichkeit soetwas ins Leben zu rufen. Die Aussage 'das will ich' ist leicht. Für eine Arbeitsgruppe die sich mit der Umsetzung dieser Aufgabe befasst würde ich gerne etwas meiner Zeit aufbringen.

Ich binn gespannt auf die Antworten...

Gruß

----------

## ralph

Eigentlich keine schlechte Idee, nur vieles von dem erreicht man doch zum einen schon durch suchen im Forum und ausserdem gibt es ja das Tips & Tricks Forum. Letzteres geht doch schon in die Richtung von dem was du dir vorstellst, oder habe ich das falsch verstanden?

----------

## ian!

Ich schreibe gerade an einem Editor zur Erstellung solcher Dokumente für gentoo-doc. (Siehe auch Mailingliste gentoo-doc.)

http://www.diefleissigen.de/cgi-bin/editorlogin.pl

Logindaten sind dort zu Demozwecken hinterlegt.

Der Editor befindet sich zur Zeit in Version Alpha2. Ist also noch in einer frühen Phase, aber man bekommt schon mal einen Eindruck.

Wünsche, Vorschläge und Kritik sind jederzeit willkommen.

Gruß,

ian!

----------

## pi

Das ist richtig, einiges steckt in "Documentation, Tips & Tricks". Ich lese diese Forum gerne und habe dort auch einiges an wissenswertem finden können und zu meiner Schande muss ich gestehen das ich einer von denen mit den Zetteln bin, auf denen irgendwelche Installationsnotizen verzeichnet sind und niemals den Weg in ein 'digitalisiertes' Leben gefunden haben. 

Ich glaube wir kennen alle HowTo's die nachher nicht funktionieren weil irgendeine Version bei mir natürlich nicht mit der übereinstimmt die jemand hatte der das Doku geschrieben hat. Also würde ein Template sehr nützlich sein in dem vermerkt wird auf welchem System mit welcher Software mit welchen USE-Flags diese Installation beruht. Den wiki Gedanken finde ich auch sehr interessant. Nach dem Motto: ich habe dieses HowTo durchgearbeitet nur ich habe anstelle apache1.3 die apache2 verwendet bzw. ich habe zusätzlich web2ldap mit installiert, achte darauf das du....

Es sollte ja erstmal darum gehen ob ein "Bedarf" erkannt wird und wenn ja dann ist mit denen die dafür Zeit aufbringen das "was und wie" zu ermitteln. Daher wollte ich mich eigentlich mit meinen Vorstellungen etwas zurückhalten um einen kreatieven Prozess zu Stande kommen zu lassen.

Gruß

----------

## pi

Als ich mit meinen letzten Post begonnen hatt gab den Beitrag von ian noch nicht.

Also existiert sogar schon ein Projekt welches dieses Problem lösen will.

Daran sieht man auch das die Vorstellungen von einem solchem Projekt unterschiedlich sein können. Ich hätte die Frage gestellt ob man versucht Konverter zu verwenden und Templates erstellt.

@ian: gibt es Doku zum Doku-Projekt  :Wink: . Meine, was soll es können, was wird verwendet und wie soll es erreicht werden?

Gruß

----------

## ian!

 *pi wrote:*   

> Also existiert sogar schon ein Projekt welches dieses Problem lösen will.
> 
> 

 

Es soll die Erstellung von Dokumentationen vereinfachen.

Normalerweise müsste man sich, um Dokumentationen erstellen will, zunächst in Guide XML [1] einarbeiten. Allein dieser Aspekt schreckt schon viele Leute ab, eine Dokumentation zu erstellen, denn die Intention war eine Dokumentation zu erstellen - nicht Guide XML zu lernen.

Zudem soll der Benutzer unmittelbar sehen können, wie das Dokument im Endeffekt aussieht. (Da macht die Sache auch direkt mehr Spass.)

 *pi wrote:*   

> Daran sieht man auch das die Vorstellungen von einem solchem Projekt unterschiedlich sein können. Ich hätte die Frage gestellt ob man versucht Konverter zu verwenden und Templates erstellt.
> 
> 

 

Konverter? Von welchem Format willst Du denn ausgehen? Das Format, in welches Konvertiert werden sollte, sollte XML sein. Und zwar solches, das dem DTD von gentoo-doc entspricht. Somit hätte man ein einheitliches Look&Feel. (Wobei die Darstellung ja durch das zugehörige XSLT bestimmt wird. Somit ist die Dokumentation nicht an die Formatierung bzw. das Design gebunden. Design und Rohdaten sind voneinander getrennt.)

Dies ist auch direkt das schlagende Gegenargument zu einem Wiki. In Guide XML hat man eine begrenzte Anzahl von Möglichkeiten etwas darzustellen. Ist ist aber kein Nachteil, sondern ein nicht zu verachtender Vorteil. Ein "Code Listing" sieht immer aus wie eins. Gleiches gilt für "Notes", "Warnings" etc. Der Leser findet sich somit direkt in der Struktur der Dokumentation wieder, da diese immer die selbe ist. Wie würden z.B. "Code Listings" in einem Wiki aussehen? Ich denke, daß dort ein Wildwuchs an verschiedensten Darstellungsformen erwachsen würde.

Es ergeben sich noch weitere Vorteile durch die Benutzung von XML. Diese würden dann aber den Post sprengen. (Und vorallem bin ich dafür jetzt zu faul.  :Wink: )

 *pi wrote:*   

> 
> 
> @ian: gibt es Doku zum Doku-Projekt . Meine, was soll es können, was wird verwendet und wie soll es erreicht werden?
> 
> 

 

Nein, es gibt zur Zeit noch keine Doku dazu. Es war von mir anfangs zunächst als "Proof of Concept" gedacht.

Das was "hinten rauskommen" soll, entspricht Guide XML, welches unter [1] spezifiziert ist. (Die genaue Spezifikation des Formates findet sich im DTD.)

Der Editor wird vielmehr als nur ein Editor sein.

Der Editor wird:

- Revisionen von Dokumenten verwalten können (ähnlich CVS, diff)

- Unterstützung zur Erstellung von Übersetzungen liefern (side-by-side editing)

- den Reviewing-Prozess beschleunigen/vereinfachen

- simultanes Arbeiten von mehreren Leuten an einem Dokument ermöglichen

- evtl. ein- / auschecken in CVS ermöglichen (muss noch erörtert werden; natürlich werden dies nur berechtigte User wie bisher auch dürfen)

- etc.

Was verwendet werden soll? Wie muss ich diese Frage verstehen? Meinst Du die dahinter stehenden Technologien? Wenn dies der Fall ist:

Software: Perl, Apache, MySQL sowie einige Perlmodule (größtenteils Eigenentwicklungen, wozu aber auch bereits Dokumentationen verfügbar sind)

Formate, Scriptsprachen: HTML 4.01, JavaScript 1.3, XML 1.0, CSS1

Wie soll es erreicht werden?

Mhh... jemand setzt sich hin und programmiert sowas. Jemand anderes testet die Software und reported Bugs. Vorschläge und Kritik wie gesagt stets willkommen.

Gruß,

ian!

[1] http://www.gentoo.org/doc/de/xml-guide.xml

----------

## AGM

 :Very Happy:  In Documentation Tipps & Tricks habe ich auch schon so einige Sachen gefunden, die mich auf die Idee gebracht haben, was auszuprobieren, oder die mir eine bessere Möglichkeit aufgezeigt haben irgendwas zu lösen, von daher bin ich von ian! 's Idee sehr begeistert!

----------

## mflatischler

 *ian! wrote:*   

> 
> 
> http://www.diefleissigen.de/cgi-bin/editorlogin.pl
> 
> Wünsche, Vorschläge und Kritik sind jederzeit willkommen.
> ...

 

Frage: Unter welchem Lizenz lässt du dein Projekt? GPL oder *BSD oder auch andere?

Wunsch: Ich könnte als Advisor/Mentor/Consultant für dieses Projekt arbeiten, ich hatte schon ein Plan gehabt so ein ähnliches Projekt anzufangen, wusste nicht aber von wo *chaotisch im Hirn*.

mail mir einfach!  :Wink: 

Vorschläge: werde ich dir per mail schicken, in deinem Forum posten oder mittels irc/jabber(finde ich aber als schlechte Lösung) 

Kritik: CGI-Perl(-skripte) sind schön und gut, aber der Nachteil den du auch sicherlich kennst ist, dass CGI-Perl viel Resourcen in Anspruch nehmen. 

Vorschlag: PHP könnte Abhilfe schaffen, bringt natürlich auch Nachteile mit sich gegenüber CGI-Perl. Kombination aus dem Beiden auch ok. Perl und PHP -Versionen auch ok.

----------

## ian!

 *gentle2gentoo. wrote:*   

> 
> 
> Frage: Unter welchem Lizenz lässt du dein Projekt? GPL oder *BSD oder auch andere?
> 
> 

 

GPL, soweit es in einem Status ist, in dem es benutzbar ist.

Dann werde ich Sourcen usw. öffentlich machen.

 *gentle2gentoo. wrote:*   

> 
> 
> Kritik: CGI-Perl(-skripte) sind schön und gut, aber der Nachteil den du auch sicherlich kennst ist, dass CGI-Perl viel Resourcen in Anspruch nehmen. 
> 
> Vorschlag: PHP könnte Abhilfe schaffen, bringt natürlich auch Nachteile mit sich gegenüber CGI-Perl. Kombination aus dem Beiden auch ok. Perl und PHP -Versionen auch ok.
> ...

 

Es wird definitiv zunächst nur eine Perlversion geben. Das aus dem Grund, da man soetwas mit Perl IMHO am schnellsten erreichen kann. Ob PHP da schlanker ist, wage ich zu bezweifeln. Vorallem spielen die benötigten Ressourcen nicht wirklich ein Problem. Die jetztige Version ist weder optimiert, läuft nicht persistent im Speicher und liegt auf meinem Homewebserver, der mit statischer IP mit ADSL (768/128) am Internet hängt.

Gruß,

ian!

----------

## toskala

auch wenn ich normalerweise meinen vi echt liebgewonnen habe, das ding sieht schon funky aus.

weiter so

----------

## ian!

 *toskala wrote:*   

> auch wenn ich normalerweise meinen vi echt liebgewonnen habe, das ding sieht schon funky aus.
> 
> weiter so

 

Danke, danke!

"Alpha 3" folgt am 17.09.

Gruß,

ian!

----------

## ian!

Vorschläge zur Usability von "gentle2gentoo.":

 *gentle2gentoo. wrote:*   

> 
> 
> 1. Betreff: Delete Button 
> 
> Es sollte nicht neben jedem Textelement ein Delete-Button stehen. Vielmehr wäre es wünschenswert, daß zu löschende Elemente anhand einer Checkbox zu selektieren sind. Die Löschaktion soll dann über einen Delete-Button in der unteren Toolleiste erfolgen.
> ...

 

Allesamt gute Ideen, wie ich finde. Diese Features werden aber sicherlich erst in Alpha4 implementiert sein. Alpha3 folgt wie bereits angekündigt heute Abend.

Weitere Vorschläge, Kritiken?

Gruß,

ian!

----------

## pi

Sorry das ich solange nicht reagiert habe,

 *Quote:*   

> Konverter? Von welchem Format willst Du denn ausgehen? Das Format, in welches Konvertiert werden sollte, sollte XML sein. 

 

Ich hätte auf jeden Fall für die Erstellung von Dokumenten  dasDocBook -Format favorisiert (ist XML). Nach meinem Dafürhalten birgt es einige Vorteile, die wichtigsten:

-es ist auf die DocBook-Dokumentation verwiesen, Absatz "Motivation - Warum DocBook?"

Für DocBook gibt es auch fähige Editoren, ich verwende zum Beispiel XML Editor von XMLmind.

Man findet einige Konverter bzw. -da das Format offen ist- kann jeder selbst einen schreiben.

DocBook scheint auch unter IT'lern noch nicht wirklich bekannt zu sein, was ich sehr schade finde. Es ist sogar daran gedacht wurden, in das Format Attribute aufzunehmen über die man allen Elementen (Absätze, Tabellen, Texte etc) einen Status (Revisionsflag) zuweisen kann. 

Einen Blick ist es auf jeden Fall wert.

Gruß

----------

## ian!

 *pi wrote:*   

> 
> 
> Ich hätte auf jeden Fall für die Erstellung von Dokumenten  dasDocBook -Format favorisiert (ist XML).
> 
> 

 

Das Eine schließt das Andere ja nicht aus. Wenn man sich die DocBook DTD anschaut, so findet man schon Parallelen zu dem von Gentoo-Doc verwendeten. Beides ist XML.

Wie der Editor das XML dann ausspuckt ist doch reine Parametrierung. Somit ist man hierbei doch erstmal kompatibel.

Vorallem ist der Editor ja in erster Linie für Gentoo bezogene Dokumentationen gedacht. Deshalb stützt dieser sich auch auf die Spezifikationen des Gentoo DTD. Das könnte man allerdings jederzeit ändern.

(Das können wir später gerne machen. Mir schwebt z.B. auch vor, aus dem XML direkt PDFs erstellen zu können. Für Offline- bzw. Druckversionen.)

 *pi wrote:*   

> 
> 
> [...] Es ist sogar daran gedacht wurden, in das Format Attribute aufzunehmen über die man allen Elementen (Absätze, Tabellen, Texte etc) einen Status (Revisionsflag) zuweisen kann. 
> 
> 

 

"Cool", aber meines Erachtens overkill. Jedenfalls zu jetzigem Zeitpunkt. Vieles kann man auch über die noch zu implementierenden "Notizen" abbilden.

 *pi wrote:*   

> 
> 
> Einen Blick ist es auf jeden Fall wert.
> 
> 

 

Danke jedenfalls für die URLs! Ich werde mir DocBook genauer ansehen und mich etwas einlesen; habe gerade nur kurz quergelesen.

Gruß,

ian!

----------

## pi

 *Quote:*   

> aus dem XML direkt PDFs erstellen zu können

 

wie gesagt, für DocBook existieren einige Konverter. 

Von XMLmind gibt es den FO Converter, der jedoch teilweise (je nach Funktionsumfang) Geld kostet.

In der ix war auch mal ein Artikel zum arbeiten und konvertieren mit DocBook.

Jetzt ist aber mein Vorrat an Links zum Thema DocBook aufgebraucht.

Für mich denkbar wäre, dass man Volagen erstellt. Wenn jemand Dokumentation erstellen will, tut er dies mit einem Editor seiner wahl. Sendet seine Dokumentation ein (über ein Webinterface), hier wird das Dokument geparst und sicher gestellt das es den Anforderungen entspricht. Dieses Dokument wird auf einem Server abgelegt. Es wird konvertiert (jetzt kommt auch das gentoo-Layout dazu  :Wink: ) und online gestellt.

Wenn jemand eine Änderung an diesem Dokument vornehmen will holt er sich die DocBook-Datei oder tut dies an einem online Editor.

Wenn man mag kann man dahinter ein cvs/subversion stellen und hätte auch gleich die Versionierung/Änderungsverfolgung sinnvoll gelöst.

Wenn sich das(oder anders) mit bem bisherigen Konzept vereinbaren liese leiste ich gerne einen Anteil bei der Umsetzung. 

Von Einmannprojekten halte ich nicht viel, nicht das kein funktionierendes Ergebniss erreicht würde. Ich glaube Ihr wisst was ich meine...

Gruß

----------

## ian!

 *pi wrote:*   

> Wenn jemand Dokumentation erstellen will, tut er dies mit einem Editor seiner wahl. Sendet seine Dokumentation ein (über ein Webinterface), hier wird das Dokument geparst und sicher gestellt das es den Anforderungen entspricht. Dieses Dokument wird auf einem Server abgelegt. Es wird konvertiert (jetzt kommt auch das gentoo-Layout dazu ) und online gestellt.
> 
> 

 

So soll es sein.

 *pi wrote:*   

> 
> 
> Wenn jemand eine Änderung an diesem Dokument vornehmen will holt er sich die DocBook-Datei oder tut dies an einem online Editor.
> 
> 

 

ACK.

 *pi wrote:*   

> 
> 
> Wenn man mag kann man dahinter ein cvs/subversion stellen und hätte auch gleich die Versionierung/Änderungsverfolgung sinnvoll gelöst.
> 
> 

 

Die Versionsverwaltung und diff soll intern abgebildet werden.

 *pi wrote:*   

> 
> 
> Wenn sich das(oder anders) mit bem bisherigen Konzept vereinbaren liese leiste ich gerne einen Anteil bei der Umsetzung. 
> 
> Von Einmannprojekten halte ich nicht viel, nicht das kein funktionierendes Ergebniss erreicht würde. Ich glaube Ihr wisst was ich meine...
> ...

 

Es soll ja auch kein Einmannprojekt bleiben. Wenn Du möchtest, könntest Du dich mit DocBook auseinandersetzen und diesen Teil implementieren. Wenn Du wirklich mit einsteigen wollen würdest, dann müsste ich auch schon recht zeitnah eine Projekthomepage fertigmachen.

Würdest Du dich denn für die Realisierung des DocBook-Parts interessieren?

Gruß,

ian!

----------

## pi

@ian

ich habe mich wohl etwas missverständlich ausgedrückt. Meinte, ich hätte keine Lust als Einmannprojekt daran zu werkeln.

 *Quote:*   

> Würdest Du dich denn für die Realisierung des DocBook-Parts interessieren? 

 

Dem ist so, wir solltens uns jedoch dann als erstes abstimmen.

Stimmt die Mailadresse bei web.de?

Gruß

----------

## ian!

 *pi wrote:*   

> @ian
> 
> ich habe mich wohl etwas missverständlich ausgedrückt. Meinte, ich hätte keine Lust als Einmannprojekt daran zu werkeln.
> 
> 

 

Ach so!  :Wink: 

Na, daß bekommen wir schon hin!

 *pi wrote:*   

> 
> 
> Stimmt die Mailadresse bei web.de?
> 
> 

 

Ja.

Gruß,

ian!

----------

## ian!

Alpha3 released:

http://www.diefleissigen.de/cgi-bin/editorlogin.pl

Changelog und Projectsite folgen zur Alpha4.

Wünsche, Vorschläge und Kritik sind jederzeit willkommen. 

Gruß, 

ian!

----------

## pi

Mit Opera kommt es zu einem Darstellungsfehler.

Gruß

PS: hast Du meine Mail erhalten?

----------

## ian!

 *pi wrote:*   

> Mit Opera kommt es zu einem Darstellungsfehler.
> 
> 

 

Ah ja! Werde ich beheben.

 *pi wrote:*   

> hast Du meine Mail erhalten?

 

Klar. Wollte nur erst einige Gedanken sammeln und meinen Hirnschmalz in gesammelter Form bei Dir abgeben. Ich denke heute Abend werde ich dafür etwas Zeit finden.

Gruß,

ian!

----------

## wuschel

Hi ian!

Benötigt man bestimmte Browser-Einstellungen zur vernünftigen Darstellung deines Editors?

Mein Linux-Opera (7.20Beta7) stellt nämlich gar nichts dar.

Mit Linux-MozillaFirebird 0.6.1 geht's dagegen.

----------

## ian!

 *wuschel wrote:*   

> Hi ian!
> 
> Benötigt man bestimmte Browser-Einstellungen zur vernünftigen Darstellung deines Editors?
> 
> Mein Linux-Opera (7.20Beta7) stellt nämlich gar nichts dar.
> ...

 

Javascript wird vorausgesetzt.

Eigentlich sollte der HTML-Source dem HTML4.01 Strict Standard entsprechen. Wo hakt es denn? In welchem View, bei welcher Aktion?

Gruß,

ian!

----------

## wuschel

Nach dem Einloggen und Auswählen eines Docs (Gentoo XML Guide) und Druck auf "Edit" passiert schlicht und einfach nüscht.

 *ian! wrote:*   

> Javascript wird vorausgesetzt.

 Ist an.

Da es aber in Firebird läuft gehe ich eher von einer Opera-Macke aus.

Ist ja auch ne beta.  :Wink: 

Edit: ...und ich bin auch schon gar nicht mehr auf dem Laufenden, mittlerweile gibt's die B12.

Werde die mal testen und mich wieder melden.  :Smile: 

----------

## ian!

So.

Wie versprochen habe ich mich einem Rewrite des Editors gewidmet. Vieles funktioniert schon und könnte theoretisch zur Erstellung von Dokumentation genutzt werden. Allerdings fehlen mir noch etliche Sachen, die ich noch implementieren möchte. Was der aktuelle Stand (Version pre1) hergibt ist ein WYSIWYG-Editor mit Guide-XML und PDF-Export.

Wer mal probefahren möchte:

http://213.146.113.231/cgi-bin/gendocedit/index.pl

(Login-Button oben rechts)

User: gentoo-forums

Passwort: demo

Kritik, Mithilfe und alles weitere gerne und jederzeit willkommen!

Gruß,

ian!

----------

## jay

Das Projekt sieht jetzt schon vielversprechend aus.

Dinge, die mir noch aufgefallen sind. 

- Im Text-Modus solle es einen Button "Insert Link" geben, der automatisch

  <uri link="...your link here..."> ... </uri> einfügt.

- Der OK Button sollte im Editiermodus nicht nur unten, sondern auch rechts von der Textbox sein (hab zuerst lang gesucht).

- Wenn man als Admin einen User hinzufügt, wird man hinterher wieder auf diesselbe Seite gebracht. Stattdessen sollte man ins Hauptmenue zurück.

- In Codelisting sollte es einen Button "Insert Codenote" geben, der

<codenote>Your note here!</codenote> einfügt.

- Codenote Tags werden nicht rot dargestellt!

- <path>...</path> Tags werden nicht in fixed width dargestellt!

- Es fehlen Punkte "Insert Ordered List" "Insert Unordered List". Diese könnten einfach für jeden Listpunkt ein Eingabefeld darstellen. Am besten sollten immer Ausgefüllte Eingabefelder + 5 freie Felder zur Eingabe dargestellt werden.

Ok, ich hoffe, ich hab Dich jetzt nicht ganz umgehauen  :Smile: 

----------

## ian!

 *jay wrote:*   

> Ok, ich hoffe, ich hab Dich jetzt nicht ganz umgehauen 

 

Nein. Das schockt mich in keinster weise.  :Wink: 

Mir ist bewusst, dass es noch viele Anforderungen zu erfüllen gibt.

BTW:

pre3 released

Changlog:

- added ui-design to 'import Guide-XML'

- added 'publish' function

- added 'modify publishing groups' to admin menu

- added 'move up' and 'move down' functions in edit view

- added another 'ok' button to edit view on the left of the selected textelement (requested by jay)

- changed redirect to 'main menu' instead of 'add user' when adding a user was successful (requested by jay)

- added abstract input to 'create new document'

- added auto-focus to inputboxes

- added 'insert link' dialog

Mehr habe ich heute nichtmehr geschafft. Der 'insert link' funktioniert auch zunächst nur insofern, das man einen Link einfügen kann. Die Daten werden allerdings noch nicht geparst.

Allerdings wollte ich heute unbedingt noch die pre3 rausbringen.

Gruß,

ian!

----------

## bmichaelsen

Es existiert hier eine Testimplementation für ein Gentoo Kernel and Hardware Wiki. Es hat sich dort auch bereits etwas an Infos angesammelt. Das Wiki ist von der Struktur her hauptsächlich auf Hardware und Hardwareconfiguartion ausgelegt. Wenn wir neue Ansätze in die gentoo-Docs bringen wollen, sollten wir die Ansätze vielleicht koordinieren?

Gruss, Björn

----------

## ian!

 *bmichaelsen wrote:*   

> Wenn wir neue Ansätze in die gentoo-Docs bringen wollen, sollten wir die Ansätze vielleicht koordinieren?

 

Das sollten wir wahrlich. Obwohl ich denke, dass die eine Lösung die andere nicht ausschliesst.

Der gendocedit-Editor ist hauptsächlich zur einfachen Erzeugung, Überarbeitung, Übersetzung und Veröffentlichung von Gentoo-Dokumentationen gedacht. Entstanden ist das Projekt durch Unzufriedenheit der bestehenden Dokumentation (obwohl diese ja eigentlich schon sehr gut ist). Zudem verlieren wir viel Dokumentation in den Foren und die Infos sind oft nur mühsam wieder aufzufinden. Man muss sich oft erst durch mehrere Threads hangeln um daraus eine Lösung für sein Problem zurecht zu legen.

Somit haben wir auf der einen Seite viel Knowhow (Foren) aber auf der anderen Seite keine Dokumentation, da diese nicht so einfach zu erstellen ist, wie ein Foren-Post (Guide-XML-Konventionen). Deshalb der Editor, der auf einfachem Wege Dokumentationen erzeugen und warten lässt. Hierbei sind wir auch nicht vom docs-Team abhängig, da der Editor diese selbst publizieren kann (Modul wird mit pre4 veröffentlicht).

Warum ich nicht einfach ein Wiki o.ä. aufgesetzt habe hat einen ganz einfachen Grund. In einem Wiki haben wir die Dokumentation zwar dann vorliegen, aber diese ist dann wieder nicht im Guide-XML Format vorhanden. Eine einfache Veröffentlichung auf gentoo.org oder gentoo.de wäre somit nicht ohne weitere Arbeiten möglich. Das ist aber Ziel der ganzen Sache.

Jetzt ist nur die Frage, wie wir beide Ansätze zusammenführen.

Um den Editor besser verstehen zu können skizziere ich hier mal einen Beispiel Workflow:

1.) Ein User möchte eine Dokumentation zu einem gewessen Thema verfassen.

2.) Der User meldet einen Account im Editor an. (Oder der Admin macht das.)

3.) Der Benutzer kann sofort beginnen ein Dokument zu verfassen.

4.) Sobald das Dokument aus Sicht des Users fertig ist, gibt er es frei zum Review. (Somit erlangt man eine gewisse Qualitätssicherung).

5.) Ein anderer Benutzer, der Reviewerrechte hat, schaut sich das Dokument an. Er kann dies entweder kommentieren (Verbesserungsvorschläge einbringen) und es ablehnen oder als "in Ordnung" freigeben.

6.) Der User bekommt die Freigabe und kann das Dokument veröffentlichen. Das Dokument kann er in eine ihm freigegebene Ordnerstruktur freigeben (z.B. "Desktop", "Kernel", "Hardware", "FAQ", etc.)

7.) Das Dokument ist ab sofort für alle sichtbar und kann benutzt werden.

8.) Übersetzer können das Dokument in die jeweilige Sprache übersetzen. (Hier gilt dann wieder der gleiche Prozess für diese Dokumente von Punkt 3 an.)

... Zeit vergeht ...

9.) Das Originaldokument wird überarbeitet/verändert.

10.) Es muss wiederrum reviewed und dann veröffentlicht werden.

11.) Alle von dem Dokument abhängigen Übersetzungen werden benachrichtigt, dass sich das original Dokument verändert hat.

12.) Übersetzer können das Dokument in die jeweilige Sprache übersetzen. (diff)

So ist das gedacht.

Wie bekommen wir das jetzt zusammen (Wiki & Editor)? Oder sollen wir zwei Schienen fahren und sehen, was besser angenommen wird?

Mir liegt die Erstellung von Guide-XML konformen Dokumenten sehr am Herzen. Somit würden wir den Gentoo-Doku-Standart einhalten/entsprechen und hätten mehrfach verwertbare Dokus.

Gruß,

ian!

----------

## bmichaelsen

 *Quote:*   

> Wie bekommen wir das jetzt zusammen (Wiki & Editor)? Oder sollen wir zwei Schienen fahren und sehen, was besser angenommen wird? 

 

Hmm, das Gentoo Kernel and Hardware Wiki soll sich mal zu einer Referenz für Kerneloptionen und Hardware (identifiziert nach lspci) entwickeln. Es soll eigentlich garnicht vollständige FAQs ersetzten, sodern nur kuze Infos über eine spezielle Hardware enthalten - GentooDoc ist dafür eingentlich ungeeignet, es sei denn man stellt Infos über Hardwaregruppen zusammen. Das Wiki exportiert nach XML und mit einem kleinen Python/Perl Script sollte man dort sehr schnell ein GentooDoc draus machen können. Allerdings ändert sich Hardware schneller als es bei anderen Themen der Fall ist. Ich denke also wir sollten zweigleisig fahren. Für jeden Job das passende Werkzeug.

Andere die sich mit der Besserung der gentooDocu beschäftigen und mit denen wir uns koordinieren sollten:

tobi123 Brauchen wir / Wollt ihr ein neues FAQ System?

 sehr ähnlicher ansatz oder?

telex4 http://www.newtolinux.org.uk/ Dies überscheindet sich mit deinem und meinem Ansatz.

https://forums.gentoo.org/viewtopic.php?t=13028 Bevor die noch ein Projekt starten.

Gruss, björn

https://forums.gentoo.org/viewtopic.php?t=13028

----------

## dertobi123

Wir haben: 3 verschiedene Projekte, mit 3 verschiedenen Ansätzen.

- gendocedit zielt primär darauf ab, Doku aus den Foren zu sammeln, diese so einfach wie in den Foren editieren zu können, bei Interesse wird die einfache Übersetzung in andere Sprachen ermöglicht

- Das HardwareWiki zielt darauf ab, Informationen um mögliche und unmögliche Hardware und deren Linuxunterstützung zu sammeln.

- Die Gentoo FAQ spiegelt die aktuell in den Foren am meisten und häufigsten gestellten Fragen wieder.

Nur eines der Projekte, gendocedit, ist mehrsprachig konzipiert. Bei der FAQ ist die Unterstützung meherer Sprachen prinzipiell möglich, erfordert aber einen gewissen Aufwand. Das HardwareWiki zielt rein auf die englische Sprache ab.

Nur eines der Projekte, gendocedit, nutzt GuideXMl; bzw. kann GuideXML exportieren.

Das sind meiner Meinung nach die beiden wichtigsten Punkte:

- GuideXML Kompabilität

- Mehrsprachigkeit

Ohne diese beiden Punkte wird das Rad zwangsläufig immer wieder neu erfunden werden müssen.

Die Frage wie man die GendocEdit und die FAQ unter ein Dach bekommen kann werde ich mit ian! in der nächsten Woche erörtern.

Soviel bis hierher als "Bestandsaufnahme", demnächst mehr,

Tobias

----------

## ian!

 *bmichaelsen wrote:*   

> Hmm, das Gentoo Kernel and Hardware Wiki soll sich mal zu einer Referenz für Kerneloptionen und Hardware (identifiziert nach lspci) entwickeln. Es soll eigentlich garnicht vollständige FAQs ersetzten, sodern nur kuze Infos über eine spezielle Hardware enthalten - GentooDoc ist dafür eingentlich ungeeignet, es sei denn man stellt Infos über Hardwaregruppen zusammen. Das Wiki exportiert nach XML und mit einem kleinen Python/Perl Script sollte man dort sehr schnell ein GentooDoc draus machen können. Allerdings ändert sich Hardware schneller als es bei anderen Themen der Fall ist. Ich denke also wir sollten zweigleisig fahren. Für jeden Job das passende Werkzeug.

 

Gut. Auch wenn es dann wieder dezentral ist.

 *bmichaelsen wrote:*   

> Andere die sich mit der Besserung der gentooDocu beschäftigen und mit denen wir uns koordinieren sollten:
> 
> tobi123 Brauchen wir / Wollt ihr ein neues FAQ System? sehr ähnlicher ansatz oder?

 

Wird bereits koordiniert. Ähnlicher Ansatz? Nein. Es geht mir darum die Technologie zu Verfügung zu stellen. Das wird wohl immer missverstanden.

 *bmichaelsen wrote:*   

> telex4 http://www.newtolinux.org.uk/ Dies überscheindet sich mit deinem und meinem Ansatz.

 

Sehe ich nicht so. Wo sind da die Überschneidungen? Ich sehe das CMS nicht.

 *bmichaelsen wrote:*   

> https://forums.gentoo.org/viewtopic.php?t=13028 Bevor die noch ein Projekt starten.

 

Scheint mir bereits gestorben zu sein. Ebenso churchers Projekt.

Gruß,

ian!

----------

## bmichaelsen

 *Quote:*   

> Wir haben: 3 verschiedene Projekte, mit 3 verschiedenen Ansätzen.
> 
> - gendocedit zielt primär darauf ab, Doku aus den Foren zu sammeln, diese so einfach wie in den Foren editieren zu können, bei Interesse wird die einfache Übersetzung in andere Sprachen ermöglicht
> 
> - Das HardwareWiki zielt darauf ab, Informationen um mögliche und unmögliche Hardware und deren Linuxunterstützung zu sammeln.
> ...

 

Das sieht nach einem Erfolgsversprechenden Triumirat aus  :Wink: 

 *Quote:*   

> Wird bereits koordiniert.

 

Cool! Sorry, ich habe in den Forum nur nach Wiki gesucht und endlos viele Posts gefunden, die ich   :Embarassed:  aufgrund der Menge nicht alle gelesen habe. Vielleicht sollten die drei Projekte auch noch einmal in einem der englischen Posts erwähnt werden, um zu zeigen, dass sie koordiniert sind. Der Wust an alten Posts macht das Suchen nach solchen Projekten nicht gerade leicht.

 *Quote:*   

> Das HardwareWiki zielt rein auf die englische Sprache ab. 
> 
> 

 

Prinzipiell unterstützt moinmoin, auf das das Wiki aufbaut, Mehrsprachigkeit. Ich halte dies angesichts des Thema aber für schlichtweg nicht praktikabel. Falls man irgendwann einmal ein Auszug macht, und diesen dann nach GuideXML wandelt, kann man über Übersetzung reden.

Danke für eure schnellen Antworten!

Gruss, Björn

----------

## ian!

pre4 released. 

Changelog: 

- webserver update to apache 2.0.48. 

- added surname and givenname input to 'add user' 

- changed redirect to 'edit view' when a new document is created in 'create new document' (requested by masseya) 

- links are displayed in 'view xml' and 'view'. see bug #2. 

- abstract is filled with content in xml-output 

- parser for: [e] (emphasis), [b] (bold), [c] (codeline) 

- added dialogs for 'insert bold', 'insert italic', 'insert codeline'

http://213.146.113.231/cgi-bin/gendocedit/index.pl

(Login-Button oben rechts) 

User: gentoo-forums 

Passwort: demo

----------

## jay

Habe pre4 getestet:

- Drückt man in den Codeline/Insert Link/ Italic "Enter" statt auf OK zu klicken, dann wird die Eingabe nicht übertragen und die Seite im Popup-Fenster geladen.

- Popupfenster sind in Epiphany zu klein (Ok Cancel Button aus dem Sichtfeld), aber in Mozilla genau richtig.

- Insert Link/ Italic /Bold /Codeline sind auch innerhalb Note, Important und Warning zugelassen! Buttons fehlen hier noch. Bold und Italic werden

schon korrekt dargestellt. Nur Links und Codelines noch nicht.

- Fügt man einen fehlerhaften (zb vergessenes <) URI Link in Note hinzu, dann integriert gendocedit die edit tags in zu bearbeitenden Text !! Beim erneuten Bearbeiten wird der Code von Gendocedit innerhalb des Textareafeldes sichtbar.

----------

## ian!

pre5 released. 

Changelog: 

- minor ui enhancements

- added multi-language-ui support

- added german-ui-language-kit

- fixed bug #3

- review function complete

- documents can be published now (internal publishing function)

http://213.146.113.231/cgi-bin/gendocedit/index.pl

(Login-Button oben rechts) 

User: gentoo-forums 

Passwort: demo

So. Nun ist der Editor auch in deutsch verfügbar. Andere Sprachen sollen folgen. Hierfür wird eure Hilfe benötigt.

Desweiteren gibt es einen kleinen Vorgeschmack auf den "Publisher"; also jene Seite des Editors, die die veröffentlichten Dokumente anzeigen kann. Somit könnte man fast schon produktiv gehen. (Wenn auch nur für einfache Dokumente.)

Den Publisher findet ihr hier:

http://213.146.113.231/cgi-bin/gendocedit/gendocpublisher.pl

Ich habe zunächst nur zwei Dokumente "gepublished". Das soll einfach mal zeigen, wie soetwas aussehen könnte. Ein ordentliches Layout folgt.

Have fun,

ian!

----------

## jay

Ich hätte noch einige Vorschläge:

- Statt der Option "Anzeigen" doch den Dokumentnamen direkt als

 Link setzen. Oder evtl. auch zusätzlich. Wirkt für mich etwas intuitiver.

- Einen Menuepunkt "Optionen" oder "Dokumentoptionen" hinzufügen, wo man dann z.B. Dokumentnamen, Sprache, Autoren, Version, Abstract, Lizenz etc.. wieder ändern kann (bislang geht das nur z.T. via Neues Dokument erstellen)

- Wenn ein neues Dokument erstellt wurde, ist die Seite bis auf die Tools unten ganz leer. Eine kurze Message a la "This document contains no data yet" wäre ganz nett - ist aber kein Muss  :Smile: 

- Beim Verschieben gibt es bislang nur eins rauf/bzw eins runter. Evtl. wäre ein "To Top" und "To Bottom" auch nicht schlecht.

Wie kann ich denn die Publish-Funktion testen? Braucht man dazu spezielle Rechte?

Kleine Bugs:

- In der Deutschen Version sind z.T. einige Zeilen noch englisch, so z.B.

 "Sie haben Sich erfolgreich abgemeldet. You will be redirected to..."

-Ausserdem hat *hust hust* IE ein Problem mit der view as PDF Darstellung. Er meldet die Datei "index.pl" als unbekannt.

- Der IE zeigt ausserdem das zu bearbeitende Dokument immer ganz oben an. Das ist sehr lästig, wenn man z.B. ein Textfeld hinzufügt und dann bei längeren Dokumenten immer nach unten scrollen muss.

----------

## ian!

pre6 released!

Changelog:

- minor changes (corrections)

- editView: info if page is empty (requested by Jens Schittenhelm)

- link to 'view document' changed to document name. (requested by Jens Schittenhelm)

- rows are highlighted in 'browse documents' for easier navigation

- added 'user input' and 'codenote' to codelisting edit

- added dialog for 'insert email-address'

- fixed bug #4

- fixed bug #2

Und wie immer:

http://213.146.113.231/cgi-bin/gendocedit/index.pl

(Login-Button oben rechts) 

User: gentoo-forums 

Passwort: demo 

Gruß,

ian!

----------

## ian!

pre7 released... Produktionsumgebung online!

Changelog:

- database to use can be set in source now

- htdocs base can be set in source now

- added 'delete'-function for admins to delete documents

- added 'set user publishing rights'

- included publisher

Die Testumgebung findet sich hier:

http://213.146.113.231/cgi-bin/gendocedit/index.pl

User: gentoo-forums

Pwd: demo

Die Produktionsumgebung hier (Benutzerregistrierung notwendig!):

http://213.146.113.231/cgi-bin/gendocedit_production/index.pl

Hier sieht man ein Beispieldokument, welches mit dem Editor erstellt und veröffentlicht wurde: http://213.146.113.231/cgi-bin/gendocedit_production/index.pl?action=publisher&actionData0=2&actionData1=&actionData2=3

Wenn jemand Zugriff auf die Produktionsumgebung braucht, um Dokumentation zu schreiben, so maile man mir oder schicke eine PM an mich.

Gruß,

ian!

----------

## jay

Und hier wieder meine Vorschläge:

-> rows are highlighted in 'browse documents' for easier navigation 

a) Dies am besten auch für "modify publishing groups" einführen. 

b) Der Gruppenname sollte ein Link sein und sollte dann das "browse documents" fenster öffnen, aber nur die Dokumente anzeigen die in dieser Gruppe published wurden. -> das wäre echt cool.

Neben Admin - Editor - Guest sollte es noch eine vierte Gruppe geben: "Locked" Benutzer dieser Gruppe sind komplett gesperrt. "Guests" sollten zumindest noch die Dokumente betrachten können.

Eventuell auch noch eine fünfte Gruppe "Reviewers" ..? Diese können Dokumente revoken oder review ok durchführen, aber keine Dokumente publishen (dies nur Editoren) oder auch umgekehrt.

In browse Documents sollte neben "Show languages" auch noch ein Drop-Down-Menue "Show Status" mit allen möglichen Statusoptionen

geben. Dann kann man blitzschnell alle Dokumente sehen, welche z.b. noch work in progress o.ä. sind.

 :Very Happy: 

----------

## ian!

Erstmal ein dickes Dankeschön an jay, dertobi123, gentle2gentoo, carambola2 und alle anderen die sich bisher eingebracht haben!

pre8 released!

Changelog:

- rows are highlighted in 'modify publishing groups' and 'search documents' for easier navigation (requested by Jens Schittenhelm)

- added 'reviewer' to 'browse documents' table

- editView: added auto-focus on element that is selected for edit

- fixed a grave bug (I do _not_ want to explain this any further  :Wink: )

- fixed bug #5 (changed pdf generation process)

- added a 'refresh'-button in 'browse documents'. (useful if you want to see if changes were made in the meantime)

- added 'path'-tag dialog and parser

Testumgebung:

http://213.146.113.231/cgi-bin/gendocedit/index.pl

(User: gentoo-forums Pwd: demo)

Produktivumgebung:

http://213.146.113.231/cgi-bin/gendocedit_production/index.pl

Publisher:

http://213.146.113.231/cgi-bin/gendocedit_production/index.pl?action=publisher

Dokumente folgen... wer selbst Tätig werden möchte, maile mir bitte an die im Editor angegebene eMail-Adresse.

Gruß,

ian!

@Jay: Ich bleibe dran. Deine Vorschläge sind allesamt sehr gut. Auch wenn ich nicht so schnell hinterherkomme. Deine Vorschläge sind notiert (wenn auch nicht in der Wishlist) und werden nicht vergessen. Danke nochmal!

----------

## ian!

Nur der Vollständigkeit halber:

pre9 released

Changelog:

- hopefully fixed some special character issues (german charset; needs testing)

- added 'create copy' of document function

- added treeview to 'browse documents' to display relationships/history of documents

- added functions to create and manage subgroups of publishing-groups

Have fun,

ian!

----------

