UDP - User Documentation Project

[henfri]

Ich würde mir schreibrecht auf die Dokumentation wünschen. Dann kann ich auch etwas beitragen

von Unterwegs getippert

[callidomus]

Hallo Hendrik und Jochen,

klingt gut. Besorgt Euch einfach einen github account und Ihr könnt im Wiki loslegen.
Zusammen mit greentux wollen wir da ein deutsche Benutzeranleitung entstehen lassen.

Bis bald

Marcus

[henfri]

Hallo,

ich habe bisher auf dem Wiki nur das DWD-Plugin gesehen..
Schon da war mir die Trennung zw. Homepage und Wiki nicht klar.
Sollten wir nicht nur eine Quelle haben?
Github-User: henfri

Gruß,
Hendrik

[callidomus]

Hi Hendrik

die Idee ist es ein Art deutsches Handbuch im Wiki zu erstellen. Es geht nicht um eine 1:1 Übersetzung.
Das englische Homepage soll die technische Basis bilden auf der alle Features der Plugins & Co dokumentiert werden. Das Handbuch sollte den Benutzer besser bei 08/15 Aufgaben führen.

Jeder github-User kann momentan im Wiki editieren.

Bis bald

Marcus

[henfri]

Hallo,

ich finde die Idee nicht gut.
Das wird dazu führen, dass sich die einzelnen Anleitungen widersprechen. Wir werden nicht beide Anleitungen pflegen können.

Warum pflegen wir nicht *eine* Dokumentation? Die Sprache ist mir egal.

Gruß,
Hendrik

[greentux]

Die Entwickler schreiben ihre - eher technische - Doku direkt ins plugin directory, aus dem mknx dann die Homepage generiert.
Das Wiki soll das drumrum bieten (Howto, Beispiele, etc.) und auf Deutsch sein, da dann die Einstiegshürde geringer ist (auch beim Input).

Marcus, dann müsste die Wiki Seite jetzt verdeutscht werden?

[2ndsky]

Support für SmartHome.Pi

Wir werden nicht beide Anleitungen pflegen können.

Wie greentux schon geschrieben hat, die eine Doku wird vom Entwickler gepflegt. Das sollte wirklich nur die Funktion kurz und prägnant beschreiben.

@Marcus
Vielleicht würde da eine automatisch generierte Doku sogar mehr sinn machen. Dann wären alle Entwickler ein wenig mehr zur Doku im Plugin verpflichtet und man hätte diese auch gleich im Code anstatt an zwei stellen zu pflegen (ala Doxygen).

[callidomus]

Hallo Niko,

@Marcus
Vielleicht würde da eine automatisch generierte Doku sogar mehr sinn machen. Dann wären alle Entwickler ein wenig mehr zur Doku im Plugin verpflichtet und man hätte diese auch gleich im Code anstatt an zwei stellen zu pflegen (ala Doxygen).

ja, das ist eine gute Idee. Hast Du gute Erfahrungen mit doxygen gemacht?
Es sieht ja recht mächtig aus. Pydoc kann nur HTML, dafür könnte man da auch gleich Testfälle definieren.

Bis bald

Marcus

[2ndsky]

Support für SmartHome.Pi

HTML würde ja reichen. Doxygen kenn ich aus der C Entwicklung, mit Python geht es zwar, habs aber noch nicht probiert. Doxygen kann halt auch Beispiele einbinden, die man in extra Dateien definieren kann. Wäre für uns vlt. ganz praktisch. Welches Tool wir letztendlich verwenden ist mir aber egal.

[henfri]

Ich denke dennoch:
In der Doku auf der Projektseite steht ja schon das Meiste drin. Einiges ist aber nicht aktuell, oder ich hätte mir hier und da zwei, drei Worte zusätzlich gewünscht. Dafür muss ich aber nicht die ganze Doku ins Deutsche übersetzen/noch mal neu erstellen...

[callidomus]

Hi Hendrik,

ich kann Dich auch einfach für die normale Seite freischalten.

Ich finde aber auch eine Art Benutzerhandbuch ansprechend. Der Fokus ist halt nur ein anderer.

Bis bald

Marcus

[ozett]

hallo,
ich habe jetzt an unterschiedlichen stellen meine ersten erfahrungen mit smarthome/smartvisu hier gepostet.

ich bin (noch) quasi der noob, der mal eine erste installation ans laufen bekommen möchte und sich die infos zusammensucht. und genau diese ist jetzt gerade ja auch notwendig, denke ich. man sucht hier im forum, auf den smarthome seiten und im den drei start-readmes im smartvisu-wiki. dazu checkt man noch einige samples durch. wenn DAS zentral wäre (auch diese komische nicht-trennung von smarthome und -visu nicht mehr wäre das schon super.

vielleicht auch genau so:

1) doku/wiki (anfänger,entwickler)
2) syntax-lexikon
3) samples (mit comment)

also so _eine_ zentrale dokustelle fände ich gut.
da könnte man schneller orientiert sein, was son anfänger wissen muss, um ans rennen zu kommen. erfolg motiviert auch mehr.

und hilfreich sind dann ja immer technische doku der entwickler. über syntax und den letzten stand von attributnamen etc., um sich zu vergewissern. man kennt das meist so aus dem fritzbox modden (freetz) oder wenn images auf die ganze nas-server gebracht werden. daher zumindest bin ich so gewisse üblichkeiten gewohnt...

so ausm stand, und ich bin ja hier mit smart-x als noob am anfang, vermisse ich ganz extrem eine aktuelle und vollständige beschreibung der atrribute/syntax der items.conf. sonst kommt man nicht wirklich so ans rennen, sondern macht immer nur dieses leicht de-motivierendes try-error-fixing...

das UDP projekt ist super. oben anpinnen vielleicht?

gruss,ozett

[fanta2k]

Besorgt euch doch eine confluence installation, diese ist für OS projekte auch kostenlos.

Das wiki auf github ist für einen End-Nutzer nicht das wahre, über confluence hat es dann auch jeder um einiges einfacher der dazu beitragen möchte.

[Dragonos2000]

Ich denke dennoch:
In der Doku auf der Projektseite steht ja schon das Meiste drin.

Ja, das stimmt schon. Aber wenn ich so an meine ersten Schritte mit SV/SH zurückdenke, dann tat ich mir damit auch schon schwer, da ich manches einfach nicht so richtig greifen konnte.
Andere Dinge finden sich dann erst durch Forumssuche oder Nachfragen.
Wie Du schon geschrieben hast: Ein paar konkrete Beispiele mehr machen auch schon vieles klarer.

...jetzt besorg' ich mir erstmal einen github Account...

Gruss
Jochen.

[greentux]

Ja, in der Tat sind die Anforderungen der User, die ich hier beobachten konnte, in etwa wie folgt:

- kurze knackige Anleitung, um sh.py / smartvisu ans fliegen zu bekommen (Variante: mit Rasberry Image, Variante: auf nem Standard Debian). Hier gabs auch hin und wieder den Wunsch, das in Deutsch zu haben.
- Verschiedene Howtos (Import ETS, Umstieg von linknx)
- Beispiele aus dem Leben (Logik für Abwesenheitserkennung mit PMs, halt alles, was schon bei linknx etc. immer mal auftauchte bzw. als WG Plugin/Logik vorhanden ist)

Die Wiki Startseite könnten wir entsprechend strukturieren und dann kanns auch schon losgehen.