Comment The docs infrastructure person pipes up (Score 2, Informative) 179
I didn't realize this thread was already going when I posted, so I'm pasting it in again here:
This is what we do. It works, and it solves many of the issues associated with traditional documentation "systems".
1. Define a DTD of the elements you will need in your documents. You can go with a predefined DTD like DOCBOOK, or you can roll your own. Because my goal was to get engineers to write as many documents as possible (thereby making my life easier), I chose to create my own DTD - There's about 60 elements. Special documents (like projects, or resumes, for example) have their own
DTD (and XSL) in order to keep the main documentation DTD as simple as possible.
2. Create a general XSL sheet that transforms all
documents which conform to the DTD into HTML for your internal web-site - all of the presentation
logic is in this one XSL sheet (although it can use xsl:include if you'd like to break it up by header, table of contents, content, footer, etc).
3. Set up documentation sub-branch(es) in the source control system. (In the
code base and QA/infrastructure/whatever else you plan to document and publish). The closer it is to the code, the more likely that engineers will add reviewcomments, fix errors, update it, etc.
4. Anyone and everyone writing documents does so
according to DTD and checks them into the designated directory structure in the source control repository. (As far as they are concerned, this is the end of their work -- it just magically appears on the site)
5. Set up Ant to use one of the Trax processors (I use Xalan2).
6. Write general purpose ant targets to convert
documentation with general XSL sheet, build indexes, etc. Write build.xml files that call these tasks and convert/index/etc all the documentation in each sub-branch.
7. A monkey or chron-job converts the documentation and pushes it to the website.
Benefits:
Tables of Contents, Index pages, indexing, image-links, etc. are all generated. There is a much lower chance of links being broken.
Once you get the XSL right, you don't have to worry about consistency with the look and feel.
You really can just concentrate on content.
In my experience, engineers are much more likely
to use VI/emacs to edit/review a document than Word or Framemaker. The GUI XML editors are getting better...
Drawbacks:
Someone has to own the DTD, beat their head against the wonderful syntax of xslt, and be willing to decipher the Ant stack traces when things inexplicably bail.
It's not yet commonly done (or at least they don't post on may newsgroups), so often you are charging ahead without much feedback.
Technical writers are difficult to hire. We haven't tried to find another one yet, but I imagine asking people to write in XML will limit our talent pool. Of course... in theory I could make all this work with Framemaker+SGML...
This is what we do. It works, and it solves many of the issues associated with traditional documentation "systems".
1. Define a DTD of the elements you will need in your documents. You can go with a predefined DTD like DOCBOOK, or you can roll your own. Because my goal was to get engineers to write as many documents as possible (thereby making my life easier), I chose to create my own DTD - There's about 60 elements. Special documents (like projects, or resumes, for example) have their own
DTD (and XSL) in order to keep the main documentation DTD as simple as possible.
2. Create a general XSL sheet that transforms all
documents which conform to the DTD into HTML for your internal web-site - all of the presentation
logic is in this one XSL sheet (although it can use xsl:include if you'd like to break it up by header, table of contents, content, footer, etc).
3. Set up documentation sub-branch(es) in the source control system. (In the
code base and QA/infrastructure/whatever else you plan to document and publish). The closer it is to the code, the more likely that engineers will add reviewcomments, fix errors, update it, etc.
4. Anyone and everyone writing documents does so
according to DTD and checks them into the designated directory structure in the source control repository. (As far as they are concerned, this is the end of their work -- it just magically appears on the site)
5. Set up Ant to use one of the Trax processors (I use Xalan2).
6. Write general purpose ant targets to convert
documentation with general XSL sheet, build indexes, etc. Write build.xml files that call these tasks and convert/index/etc all the documentation in each sub-branch.
7. A monkey or chron-job converts the documentation and pushes it to the website.
Benefits:
Tables of Contents, Index pages, indexing, image-links, etc. are all generated. There is a much lower chance of links being broken.
Once you get the XSL right, you don't have to worry about consistency with the look and feel.
You really can just concentrate on content.
In my experience, engineers are much more likely
to use VI/emacs to edit/review a document than Word or Framemaker. The GUI XML editors are getting better...
Drawbacks:
Someone has to own the DTD, beat their head against the wonderful syntax of xslt, and be willing to decipher the Ant stack traces when things inexplicably bail.
It's not yet commonly done (or at least they don't post on may newsgroups), so often you are charging ahead without much feedback.
Technical writers are difficult to hire. We haven't tried to find another one yet, but I imagine asking people to write in XML will limit our talent pool. Of course... in theory I could make all this work with Framemaker+SGML...
