|
I'm tasked with writing and updating some manuals. We have 3 software manuals, and like 7 versions of hardware manuals for different models which are all slightly different from each other. And maybe 15 option manuals. So when some basic feature gets updated, I get to have the fun of going through maybe 10 documents to change a paragraph and a few pictures. And sometimes adding a picture to the middle of a word document, and renumbering all of the following pictures (Figure 1-5 now is Figure 1-6, and what was Figure 1-6 is now Figure 1-7, ad nauseam). Or a new feature is added, which means a new chapter needs to be added, which means all the following chapters need to be re-numbered, including section numbers and sub-section numbers and image numbers.
So I get to thinking, there's got to be a better way to do this. (I tend to start thinking when doing something that boring.) Instead of keeping 20 different Word files, I'd really like to keep maybe 100 different smaller files, each holding a chapter. And a database of images.
Then when we need a manual for System X, we pull together the needed chapters and compile them, inserting the chapter number wherever a special character that marks "chapter number here" is found. Images are linked to the database, not contained within the document themselves. Template based on a single document, referred to at time of compilation.
Aside from being motivated by laziness, I think this would result in a much better maintained set of documentation. 5 minutes on Google tells me nothing exactly like (or even very close to) what I'm thinking of has already been done. So what obvious problems are here, other than the fact that I'd probably work a lot harder making such a documentation-handling software than I'd ever do updating stuff by hand?
  
|
are there that many updates to the manual to justify creating a more efficient system? :d
|
Hungary11291 Posts
Did you consider LateX? It fixes many of the problems you described, as it structures the formatting, the table of contents and the chapter numbering directly when you compile it. It also allows putting together a master document which calls minor ones and thus you can comment out whatever you don't need at any moment.
|
|
|
efb; But DocBook is better for you i promise ;]
|
Oh! I thought LaTeX was like... for... math equations -.- never actually looked at it.
Thanks for the links. I was thinking of trying to implement something in XML, but apparently DocBook beat me to it.
|
DocBook is probably best for this although I don't know anything about it.
I do know about LaTeX, though. It's not just for math equations and stuff... it excels in that area (no competition), but it's very general purpose otherwise, you can use it for most articles, letters, anything really... If you want to create really professional looking documents without having to worry about designing it right, then you use LaTeX. It's very easy to impress people with LaTeX documents (presumably because almost everyone only knows the typical Word crap).
|
thedeadhaji
39489 Posts
definitely latex, it can do exactly what you've described by "importing" smaller sections of text etc into the final package.
|
|
|
|
|
|
EPT
