Forum: Offtopic Einfache Dokumentation


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Hey Jungs!

Ist es irgendwie möglich Dokumentationen, Spezifikationen, Technische 
Anweisungen und der gleichen einfach und versionsverwaltet zu erstellen?

Hab die Nase voll.
Habs mit dem Word nun satt.

Nie passt was, oder man findet die Funktion gerade nicht etc.
Wenn man schreibt, verhindert einem die unpassende Formattierung immer 
wieder das Schreiben.
Mal hier eine Änderung der Fußzeile, da die Kopfzeile, dann verrutscht 
ein Bild in der Kopfzeile, dann ist wieder die Einteilung des ganzen 
Dokuments hin etc.

Ich hab vor dem ganzen Schlammassel ein Ende zu machen.
Wollte Asciidoc(tor) benutzen, aber die Firma möchte gerne Docx und pdf 
haben, damit sie wenn mal wer anderes weiter an den Projekten arbeiten 
muß, die Dokus weiter bearbeitet werden können.
Die Firma ist eine große, kann also eingebranntes Verhalten nicht 
ändern, nur mich irgendwie anpassen.

Ich bin für die Text Variante, da man das sehr gut auch in Subversion 
verwalten kann.

Asciidoc (oder ähnliches) --> docx mit Hilfe von Templates --> Docx --> 
pdf

Asciidoc ist ganz leserlich, und die Asciidoctor variante kann noch 
bissl mehr. Das mit den Vorlagen wird dann aber schon schwieriger.

Langsam denke ich an eine eigene in Python geschriebene Geschichte, wo 
das docx erstellt wird aus asciidoc und alle Parameter, Tags, Titel, 
Datum, Kopfzeile, Fußzeile, Inhaltsverzeichniss, Historie, usw passen,
und das Druckbild auf dem A4 auch noch gescheit ausschaut.

Bitte sagt mir wie ihr es macht...

von Christian M. (Gast)


Bewertung
-1 lesenswert
nicht lesenswert
Ich sag nur drei Worte:

LaTeX, LaTeX, LaTeX!

Gruss Chregu

von S. R. (svenska)


Bewertung
1 lesenswert
nicht lesenswert
Latex ist für sowas gut geeignet und hinten fällt PDF raus. Ob man auch 
docx erzeugen kann, weiß ich nicht.

Ansonsten könntest du mit Markdown gut fahren, ist auch bloß ASCII-Text.

von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Latex Quelltext schaut sch...e aus.
Vor Allem die begin end dinger...

Habt ihr das schonmal geschafft in die Kopfzeile ein Firmenlogo 
reinzubauen?
Dann noch dazu mehrzeilige Kopfzeile? und Fußzeile?

von Le X. (lex_91)


Bewertung
0 lesenswert
nicht lesenswert
Martin G. schrieb:
> Latex Quelltext schaut sch...e aus.
> Vor Allem die begin end dinger...

Es ist halt wichtig dass man Layout und Inhalt sauber trennt, sprich, in 
verschiedene Dateien legt.
Das hat den Vorteil dass man auch nur ein zentrales File anfassen muss 
wenn sich alle 2 Jahre die CI wieder ändert.

Die Datei mit dem Inhalt enthält dann wirklich nur relevante 
Informationen.
Denkbar wäre auch jedem Modul (bei SW-Projekten) eine eigene Doku-Datei 
beizulegen.
Ein Master-Dokument im Toplevel des Projektes inkludiert dann lediglich 
die ganzen Teildokus.

>
> Habt ihr das schonmal geschafft in die Kopfzeile ein Firmenlogo
> reinzubauen?
> Dann noch dazu mehrzeilige Kopfzeile? und Fußzeile?

Ja. Aber es ist ein Krampf, da hast du recht.
Jedes Modul kann irgendwie nicht mit einem anderen Modul, man muss sehr 
viel probieren und nachlesen.
Wenn die Arbeit aber mal gemacht ist hat man ein Master-Dokument das man 
dann eher selten nochmal anfassen muss.

: Bearbeitet durch User
von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Naja, dann hab ich immer noch kein docx mit all den header und footer 
etc.

Asciidoc --> latex --> pdf ?

Irgendwie muß ich mich damit abfinden, nie einfach Spezis zu 
schreiben...

von Alexander S. (alesi)


Bewertung
0 lesenswert
nicht lesenswert
Martin G. schrieb:
> Habt ihr das schonmal geschafft in die Kopfzeile ein Firmenlogo
> reinzubauen?
> Dann noch dazu mehrzeilige Kopfzeile? und Fußzeile?

Das sollte z.B. mit fancyhdr gehen:
ftp://ftp.fu-berlin.de/tex/CTAN/macros/latex/contrib/fancyhdr/fancyhdr.p 
df

von Jan H. (j_hansen)


Bewertung
0 lesenswert
nicht lesenswert
Martin G. schrieb:
> Nie passt was, oder man findet die Funktion gerade nicht etc.

"Nie passt was" hört sich mehr nach Frust als nach konstruktiver Kritik 
an. Und so viele Funktionen benötigt man ja nicht, die kann man sich ja 
aufschreiben oder in eine eigene Leiste packen.

> Wenn man schreibt, verhindert einem die unpassende Formattierung immer
> wieder das Schreiben.

Was meinst du damit? Die Formatierung gibst du doch selbst vor. Wie 
verhindert diese dir das Schreiben.

> Mal hier eine Änderung der Fußzeile, da die Kopfzeile, dann verrutscht
> ein Bild in der Kopfzeile, dann ist wieder die Einteilung des ganzen
> Dokuments hin etc.

Fußzeile und Kopfzeile macht man doch einmal und fertig. Da verrutscht 
dann auch nichts mehr. Und was meinst du mit Einteilung?

Word ist ein mächtiges und gutes Werkzeug, allerdings können es 
geschätzt über 80% der Anwender nicht bedienen. Ich würde dir 
vorschlagen, dich einmal intensiver mit Word zu beschäftigen und dabei 
zu bleiben. Nichts gegen Latex u.ä., aber einfacher wird es damit nicht. 
Einmal eine ordentliche Word-Vorlage erstellen und Formatvorlagen 
verwenden, dann arbeitet es sich ganz gut damit.

von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Word tut weh. Ist mächtig, aber tut immer weh, egal was man damit macht.

Es errinnert mich immer wieder an Ford Fairlane:
"Conversation with Zuzu Petals was like masturbating with a cheese 
grater: slightly amusing, but mostly painful."

Letztens hab ich es nicht gescheit hinbekommen, eine Beschriftung für 
eine Tabelle an die richtige Stelle zu setzen, und später einen 
einfachen Querverweis auf diese Tabelle einzufügen.
Es hats immer ne halbe oder ganze Seite tiefer gesetzt. Frag mal 
Microsoft wieso...
Genau wegen diesen Scheißereien mit Verweisen etc. hab' ich echte Frust, 
wie ihr schon bemerkt habt.

Kollege hat pandoc erwähnt. Habt ihr das schon mal probiert?

: Bearbeitet durch User
von Gerd E. (robberknight)


Bewertung
0 lesenswert
nicht lesenswert
Martin G. schrieb:
> die Firma möchte gerne Docx und pdf
> haben, damit sie wenn mal wer anderes weiter an den Projekten arbeiten
> muß, die Dokus weiter bearbeitet werden können.

Kannst Du ganz sicher sein, daß die, solange Du da bei denen 
mitarbeitest, nie auf die Idee kommen, etwas am docx zu ändern und Dir 
dann zurückzuschicken damit Du es weiter bearbeitest?

Wenn die das wollen, hast Du mit anderen Lösungen eigentlich fast schon 
verloren. Denn dann bräuchtest Du ein Tool um aus dem docx wieder etwas 
sinnvoll bearbeitbares zu machen. Und das ist bei docx bekanntermaßen 
schwer. Auch ein diff oder ähnliches funktioniert nur für einfache 
Änderungen, nicht für komplexere Umgestaltungen.

Ich schreibe in der Firma die Dokumentationen in Docbook und daraus wird 
per Docbook-XSL automatisiert PDF und HTML generiert. Das funktioniert 
recht gut. Das Docbook lässt sich im Oxygen-Editor ziemlich gut 
bearbeiten, Versionsverwaltung mit git geht auch gut.

Was mir am Docbook vor allem gefällt, ist daß Verlinkungen innerhalb des 
Dokuments und auf Kapitel in anderen Docbook-Dokumenten sehr gut 
funktionieren. Ich kann also z.B. aus dem Benutzerhandbuch auf ein ganz 
speziellen Absatz im Referenzhandbuch verlinken und diese Links werden 
bei Updates automatisch angepasst.

Was auch schön ist, ist aus einem Block an Basisdaten verschiedene 
Dokumente zu erzeugen. Also Quickstart, Benutzerhandbuch, 
Referenzhandbuch und Schulungsunterlagen werden aus einem Repo erzeugt. 
Ich kann dann auswählen welche Kapitel oder Abschnitte wo enthalten sein 
sollen und wo nicht.

Was beim Docbook aufwendiger ist, ist irgendwelche manuellen Eingriffe 
in die Formatierung zu machen. Auch einmal am Anfang den gesamten 
Workflow mit Basisformatierung, Zusammenstellung der Dokumente etc. in 
Makefiles zu gießen hat etwas Zeit gekostet.

Als irgendein Kunde unbedingt mal docx haben wollte, hat ein Kollege das 
HTML ins Word importiert. Das ging so lala und man musste einiges 
manuell anpassen. Ich hab gesehen daß es mittlerweile wohl auch Scripte 
dafür gibt, hab ich aber noch nicht ausprobiert.

: Bearbeitet durch User
von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Danke Gerd.

Auweia. Docbook schaut wie XML aus...

Je tiefer ich grabe umso schlimmer wirds.

Die ganzen Converter zu beherrschen, da muß ich mich mal richtig 
einlesen.

Hab auch noch http://wkhtmltopdf.org/ gefunden...
Das ist mit Asciidoc auch ganz ansehnlich.

Also zusammengefasst haben wir da folgende möglichkeiten:

Asciidoc -> HTML
Asciidoc -> ODT -> docx

multimarkdown -> PDF oder HTML oder DOCX

Latex -> PDF

Docbook -> PDF oder HTML

Alles braucht seine Zeit um sich einzulesen und vor allem einzustellen.

Pandoc kann mit reference.docx was gescheites produzieren, versteht aber 
kein Asciidoc, sondern Markdown. Passt schon.

Ich denke ich werde mal einen Blick auf asciidoctor-pdf und -odt werfen.

von Clemens L. (c_l)


Bewertung
0 lesenswert
nicht lesenswert
Martin G. schrieb:
> Docbook schaut wie XML aus...

So etwas will man nicht per Hand schreiben.

Asciidoc wurde als DocBook-kompatibel konzipiert; deshalb kann 
Asciidoctor direkt DocBook ausgeben.

von Slippin J. (gustavo_f)


Bewertung
0 lesenswert
nicht lesenswert
Noch bis vor ein paar Monaten hätte ich dir sofort zu Latex geraten.

Seit wir aber in der Firma auf AsciiDoc umgestellt haben, muss ich 
zugegeben, dass AsciiDoc besser geeignet ist. Das Schreiben damit ist 
sehr intuitiv, es gibt keine nervigen Latex-Befehle, kein 
Latex-Boilerplate-Code, Tabellen sind einfach zu erstellen und der 
Sourcecode ist im Editor sehr leserlich.

asciidoctor-pdf ist schnell installiert und hinterlässt im Projektordner 
auch keine nervigen temporären Dateien.

PS: Unter Linux kann ich das AsciiDoc-Plugin für gedit sehr empfehlen.

: Bearbeitet durch User
von Martin G. (Firma: http://www.gyurma.de) (martin_g)


Bewertung
0 lesenswert
nicht lesenswert
Hab jetzt Asciidoctor-pdf ausgereizt.
Damit kann ich wenigstens meine Handnotizen sofort meinen Chefs in PDF 
konvertiert schnell mit allem PIPAPO übergeben.
Mankos:
Kann beim Inhaltsverzeichniss keine Header und footer einstellen. Sie 
fehlen.
Kann an der Titelseite keine extra Schriften etc einfügen.
Einstellung von Firmenlogo beim Header war eine Katastrofe, aber jetzt 
passts.
Einstellung von Footer mit mehreren Zeilen ist noch schlimmer.

Es kann links und rechts Seiten getrennt behandeln, das ist gut.

Docx zu erzeugen sollte nicht schwieriger sein. Hab mit Pandoc 
experimentiert und Multimarkdown. Bin nicht weit gekommen.
Ascidoc-odt ist nochwas, was ich anschauen werde.

Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail, Yahoo oder Facebook? Keine Anmeldung erforderlich!
Mit Google-Account einloggen | Mit Facebook-Account einloggen
Noch kein Account? Hier anmelden.