Raspberry basierte Projekt - Dokumentation

I möchte euch einladen, die Dokumentation meines Projektes unter github.com/watzcraft/HauntingHouse anzuschauen.

Da ich davon ausgehe, dass das immer eine Arbeit “under construction” sein wird habe ich das mal in dem aktuellen Zustand veröffentlicht. Auch ist es kein (ausschliesslich) homegear basiertes Projekt. Ich hoffe aber dass das Ganze durch die “Vollständigkeit” der Beschreibung auch euch etwas bringt.

Wie dem auch sei, vielen Dank für das tolle Produkt!

Michael

Hallo Michael,

da hast du ja echt Arbeit reingesteckt! Ich baue gerade selbst und werde da auf jeden Fall reinschauen!

Viele Grüße

Sathya

Hallo Sathya,

nicht halb so viel Arbeit wie Du in homegear, aber danke.

Es wäre super, wenn ich Dich als CoAuthor motivieren könnte. Du hast über viele Themen schon mehr vergessen als ich lernen werde :slight_smile:

Ein breiteres Kapitel über homegear, Deine eigenen Teilprojekte im Bau, Ergänzungen/Fixes an den Linux Rezepten, neue Tweaks… Ich könnte auch als Ghostwriter Fragmente von Dir übernehmen und ausformulieren. Wenn Du Lust hast…

Grüße, Michael

Hallo Michael,

klar, gerne. Aber was hältst du davon, das Ganze dann in Blog-Form zu machen? Das hatte ich sowieso vor und das wäre doch mal ein Anreiz damit zu starten…

Viele Grüße

Sathya

Hi,

ich bin für alles offen.

Ich denke, dass die beiden Formate sich ergänzen können/sollten. Die Struktur ist einfach “anders” und ich bin aus einem Jahrhundert in dem geschriebene Bücher noch vorherrschten. Für mein Projekt habe ich hunderte von Blog Artikeln besucht und gefiltert um dann eine logische und zeitliche Abfolge reinzukriegen.

Der Blogbeitrag sollte eng umgrenzt in der Thematik und Umfang sein, es gibt wenig Möglichkeiten den Zusammenhang und Abfolge zu betonen. Ein Buch kann wichtige Schätze enthalten und man wird sie nicht finden, da der Direkteinstieg fehlt. Also könnte so eine Art WikiBook mit regelmässigen Teilveröffentlichungen bzw. die Integration des Blogartikels in eine übergeordnete Wissensbasis gut funktionieren. Ich habe nur bisher noch keine (0) Wiki Software gefunden, die das Erstellen so einer Dokumentation gut unterstützt (vor allem mit der Option auf der Generierung eines zusammenhängend lesbaren Manuals durch die Definition einer linearen Struktur innerhalb der Artikel und einer Navigationshierarchie=Inhaltsverzeichnis).

Hi Michael,

ich stimme dir zu. Buch und Blog gemeinsam macht absolut Sinn. Ich weiß auch nicht, ob es Wikis gibt, welche es ohne Weiteres ermöglichen, flexibel ein Buch zu erstellen. Das Mediawiki hat eine entsprechende Funktion, aber das Ergebnis ist nicht das Schönste. Vermutlich bleibt einem nur das manuelle Zusammenkopieren. Eine Frage wäre auch, ob Wiki oder Blog - oder beides? Was meinst du? Irgendwelche Systeme, die dir gut gefallen? Ich bin da ganz offen.

Viele Grüße

Sathya

Hallo Sathya,

ich denke, ein Blog als “Hingucker” und “schnelles Medium” ist sowas wie die Visitenkarte, würde ich also machen. Habe ich aber noch nie, bin also völlig unbeleckt.

Das Konsolidieren und Einbauen in einen Zusammenhang finde ich wichtig und würde ich auch machen. Das ist meiner Meinung nach wirklich immer ein “editorischer” Vorgang. Von Büchern, die aus Blogs generiert werden halte ich nichts. Da habe ich aber bisher kein Medium gefunden, das allen Ansprüchen gerecht wird. Meine Anforderungen wären

  • Unterstützung von mehreren Autoren
  • Online lesbar
  • Exportierbar
  • Visuell ansprechend, sowohl online als auch exportiert

Ich habe gestern nochmal meine ganzen Vorurteile gegen existierende Tools geprüft und die Wollmilchsau auch in den aktuellsten Versionen nicht gefunden.

  • Word (OpenOffice u.ä) -> Visuell ansprechend bei Bearbeitung und Publishing, Collaboration sehr aufwändig, kein online Dokument
  • Leanpub (u.ä.) -> Versionierung, Merging sehr gut, WYSIWYG schlecht, Publizierte Version visuell ansprechend aber sehr eingeschränkt. Interessant ist hier die eingebaute Monetarisierung.
  • Confluence -> Geniales Online Tool, built-in Publishing unter aller Sau, mit Plugins handelbar
  • Home Grown (z.B. Sphinx) -> Online und Offline Publishing wohl ansprechend möglich, Collaboration ähnlich wie LeanPub via GIT, kein WYSIWYG

Also, jedes der Tools gefällt mir in seinem eingeschränkten Bereich. Nicht das das irgendwie helfen würde :slight_smile:

Grüße Michael

Hallo Michael,

das Einfachste für mich wäre die Installation von Wordpress als “Blog-Klassiker”. Plugins zum Exportieren z. B. als PDF gibt es zahlreiche. Wenn es ein Plugin nicht gibt, ließe sich dieses leicht selbst schreiben. Theoretisch ließen sich sogar die Blogseiten nach definierten Kriterien in Buchform bringen, aber das ist aus meiner Sicht ohne manuelle redaktionelle Nachbearbeitung nur schwer automatisch möglich. Für die Buchform wäre Sphinx zur kollaborativen Arbeit vielleicht eine Wahl? Das verwende ich aktuell auch für die neue Homegear-Doku (doc.homegear.eu). Diese wird automatisch aus dem GitHub-Repository generiert, die kollaborative Arbeit ließe sich also über GitHub realisieren. Was meinst du?

Viele Grüße

Sathya

Klar, WordPress ist OK (habe ich schon mal gehört :slight_smile:.

Das Sphinx->PDF toolchain habe ich jetzt mal installiert. PDF auf Windows ist leider nicht sehr intuitiv und eher was für Eingeweihte, aber funktioniert. Das Ergebnis ist akzeptabel. reStructuredText ist ein sauerer Apfel, in den man wohl beissen muss…

Ich werde mal das Buch (mit Pandoc? gibt es etwas besseres?) nach reStructuredText migrieren, dann können wir das Anschauen und bei Erfolg auf der Basis in GitHub weiterpflegen.

Grüße, Michael

Hallo Michael,

wenn du irgendwelche Fragen hast, sag Bescheid. Ich habe mich ja gerade erst mit Sphinx, Sphinx und GitHub-Integration, usw. rumgeschlagen. Den Blog setze ich dann mal die Tage auf. Irgendein URL-Vorschlag? Wir können ihn natürlich auch gerne unter z. B. “blog.homegear.eu” laufen lassen.

Viele Grüße

Sathya

Mach ich.

Ich hab jetzt mal platt docx -> pandoc -> rst -> sphinx -> pdf erstellt, und siehe es kommen 150 Seiten PDF raus. Ziemlich unansehnlich, aber das kann ja noch werden.

Sobald ich etwas funktionierendes habe, committe ich das in das Git Projekt, wenn Du willst werde ich Dich gerne als Committer und Autor aufnehmen (wäre mir eine Ehre :slight_smile:.

Das mit dem Blog überlasse ich ganz Dir. Wenn Du möchtest kann ich die Domains

beisteuern.

Grüße, Michael

Hallo Michael,

ich setz das Blog dann die Tage auf :wink:. Bis Mitte nächster Woche schaffe ich das aber nicht. Domain brainstorme ich mal mit Christian. Zum Dokument steuere ich gerne meinen Senf bei :stuck_out_tongue:.

Viele Grüße

Sathya