Technische Doku: welches Werkzeug?

27/09/2013 - 12:59 von Ansgar Strickerschmidt | Report spam
Hallo NG,

wir sind gerade dabei, unsere technische Doku auf neue Füße zu stellen.
In dem Zusammenhang geht es auch darum, geeignetes Werkzeug neu
auszuwàhlen.
Folgendes sind die Rahmenbedingungen:
- Produkte sind vorrangig Single-Board Computer; von der Doku her etwa
vergleichbar mit PC-Motherboards
- es soll ein template-basiertes System entstehen, das außerdem modular
aufgebaut ist
- Rohinformationen (Signale, Steckerbelegungen, Blockschaltbilder...)
sollen in Tabellenform (bspw. Excel) oder als Pixel- oder Vektorbilder
angeliefert und extern eingebunden werden (also nicht eingebettet, sondern
als externe Datei verbleiben)
- Eine konsistente Formatierung über Stil-Vorlagen soll durch das ganze
Dokument gehen
- Web-Publishing ist nachrangig, es soll eine Papier- bzw. PDF-Doku werden.
- Automatische Versionierung wàre ein Plus.

Bisher ist MS Word im Einsatz. An verschiedenen Stellen ist mir das aber
zu unzuverlàssig und zu unpraktisch in der Handhabung; so zerlegt man sich
ein Zentral/Filialdokument recht leicht, und unübersichtlich ist es
außerdem.
Früher habe ich mal mit Corel Ventura (8) gearbeitet, das fand ich die
beste Software, mit der ich bisher zu tun hatte. Inzwischen ist das bei
Version 10 - und wird seit 100 Jahren nicht mehr gepflegt und wohl auch
nicht mehr verkauft.
Adobe InDesign schiene mir brauchbar - da mag ich Adobes Lizenzpolitik und
Abo-System aber nicht.
TeX kenne ich zuwenig - ich weiss, damit kriegt man ein sehr konsistentes
Satzbild hin, aber wie es da mit der Einbindung externer Dokumente
aussieht: keine Ahnung.
LibreOffice scheint mir àhnlich brauchbar zu sein wie Word - habe ich aber
auch zu wenig Erfahrung.
Was gibt's noch?

Also:

Was wird in Eurem Umfeld für die HW-Doku benutzt? Alles auf MS Office? Wie
verwaltet ihr Versionen und externe Dateien?
Und: Gibt es irgendwelche Erfahrungen mit spezialisierten Schulungen?

Gruss

Ansgar

Xpost & fup2 de.sci.electronics

*** Musik! ***
 

Lesen sie die antworten

#1 Uwe Borchert
27/09/2013 - 13:43 | Warnen spam
Hallo,

Am 27.09.2013 12:59, schrieb Ansgar Strickerschmidt:

wir sind gerade dabei, unsere technische Doku auf neue Füße zu
stellen. In dem Zusammenhang geht es auch darum, geeignetes Werkzeug
neu auszuwàhlen. Folgendes sind die Rahmenbedingungen:
- Produkte sind vorrangig Single-Board Computer; von der Doku her
etwa vergleichbar mit PC-Motherboards
- es soll ein template-basiertes System entstehen, das außerdem
modular aufgebaut ist
- Rohinformationen (Signale, Steckerbelegungen, Blockschaltbilder...)
sollen in Tabellenform (bspw. Excel) oder als Pixel- oder
Vektorbilder angeliefert und extern eingebunden werden (also nicht
eingebettet, sondern als externe Datei verbleiben)
- Eine konsistente Formatierung über Stil-Vorlagen soll durch das
ganze Dokument gehen
- Web-Publishing ist nachrangig, es soll eine Papier- bzw. PDF-Doku
werden.
- Automatische Versionierung wàre ein Plus.

Was wird in Eurem Umfeld für die HW-Doku benutzt? Alles auf MS
Office?



Fast, manchmal wird auf ein freies Office umgestiegen.

Wie verwaltet ihr Versionen und externe Dateien?



Gar nicht. :-(

Ich würde pdflatex aus TeXlive empfehlen. Dazu noch ein Makefile,
welches man aber manuell pflegen müsste, und man kann die Versionen
der eingebauten Dateien auch noch berücksichtigen. Aufwendig wird
aber ggf. das Festlegen des Dateibaums. Da muss man Hirnschmalz
investieren. Du hast auf oberster Ebene dokumentenübergreifende
Daten (Impressum, Adressen, Haftungsausschluss ...) und dann die
vielen projektbezogenen Dokumente. Dazu braucht man aber definitiv
geübte LaTeX-User mit viel Erfahrung bzgl. solcher Arbeiten. Eine
popelige Diplom- oder Doktorarbeit als Erfahrung langt da nicht.

Hier mal ein einfachster Aufbau, der für paar Projekte reicht:

./commons -> Disclaimer, Adressen, Formalkram ...
./template -> Eine komplette und gut gewartete Vorlage!
./project_01 -> einzelne Projekte: tex-Datei, Makefile ...
./project_01/includes -> Tabellen, modifizierte Std-Kapitel
./project_01/images -> àh? ja ...

Ich habe sowas mal privat gebastelt. Das waren paar 100 Seiten
Notizen mit insgesamt fast 1k Bilder ... Man braucht da echt ein
paar Anlàufe bis man das System raus hat. So können Grafiken und
Fotografien durchaus auch mal so was wie commons werden. Dann
müssen diese raus aus den Projekten!

PS: Auch ganz sinnvoll ist eine Verschlagwortung aller Bilder
und Grafiken sowie eine Schlagwortdatenbank. Die kann durchaus
Plain Text sein, aber sie soll/muss vorhanden sein.

MfG

Uwe Borchert

Ähnliche fragen