What tool / structure to use for technical documentation?

Question

We develop products and frameworks that will be used in our organization. I am looking for software tools for friendly programming. I once explored several options, but could not decide which one to use. I am looking for offers from people who have already used these tools.

• docbook: springframework and hibernate use this format and it looks good. but I believe that they set up the xslt / stylesheet by default. Can I copy and use their xslt and css (with changing colors and images). Can I integrate document creation using maven?

• wiki: this does not welcome authors of technical documents, and the documentation does not look professional. version is also not possible. I believe

• word docs: this is what we are currently using, but it's hard to link and reuse shared documents.

• Dita?

Answer 1

Docbook

Copy style sheets: yes , you can copy and adapt style sheets. XSL stylesheets for DocBook are very flexible, but not clear. You will need to put in a few days to make them work the way you like.

Integration Maven: yes , there are maven plugins into which you can integrate the creation of documents (for example, PDF, HTML, etc.) into the build process. We do this, including watermarks for SNAPSHOTS and deployment to Archiva at release.

Answer 2

The same question arose in our project. Up to this point, we used simple HTML and text documents, but these solutions did not satisfy.

Now we use DITA, and I really recommend it. It is lighter than the DocBook and is very well suited for software documentation.

Some pros:

• DITA allows you to separate content and style
• Separation of content and styles allows you to create documentation for various formats, such as HTML or PDF. For example, we use DITA to generate the EclipseHelp of our Eclipse RCP application.
• DITA defines a software namespace (e.g. <input> or <menu-item> , etc.)
• DITA comes with build scripts for various output formats that can be easily adapted to your specific needs.

See also DITA Open Toolkit Project Home Page

Answer 3

I'm pretty happy with DocBook, although initial overclocking (including setting up style sheets) is not so simple. But once everything is done, it is really easy to use.

I am running docbook generation from Ant build.xml through the standard XSLT task. If Maven allows you to invoke the XSLT processor, then everything should be fine.

The only drawback (I found) is the way to manage large books (not to have everything in one huge XML file)

Each chapter is a separate XML file, which, unfortunately, is not a complete DocBook file, since it is included using system objects:

  <? xml version = "1.0" encoding = "UTF-8"?>
 <! DOCTYPE article PUBLIC "- // OASIS // DTD DocBook XML V4.5 // EN"
                     "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
 [
   <! ENTITY chapter_1 SYSTEM "chapter_1.xml">
   <! ENTITY chapter_1 SYSTEM "chapter_1.xml">
 ]>

 <? xml-stylesheet href = "html.css" type = "text / css"?>

 <article lang = "en">
   <title> The Manual </title>

   & chapter_1;
   & chapter_2;

 </article>

Then chapter_1.xml looks like this:

  <section id = "chapter_1">
 ....
 </>

There may be better solutions, but I did not find them;)

Answer 4

Not sure if you are looking for additional offers or just reviews of the ones you pointed / narrowed, but ...

Python uses a combination of reStructuredText and Sphinx , which is a toolchain that I started taking at work and enjoy.

Of the ones you pointed out, I used the wiki before, and it was unpleasant for many reasons, some of which you have touched. The word also seems to be a bad choice; of those I chose docbook, but I know very little about it, so ...

Answer 5

Use the wiki.

Your objections:

this does not welcome authors of technical documents, and the documentation does not look professional. version is also not possible, I believe

There are wikis that allow WYSIWYG editing. Technical documentation for an internal project should not “look professional”. Global versioning is a problem, but I don’t see anything important in it.

On the other hand, a huge advantage of a wiki is one that cannot be rated high enough, especially for an internal product: easy input and collaboration. Each user of the product can contribute to the documentation, and if you can establish a culture of collaboration on documentation, the result will be (literally) ten times more useful than the average "Button X is a, button Y does B" technical documents created by the authors, who don’t actually use the product. No one needs them. People need Howto guides, glossaries, frequently asked questions, and workarounds.

Wikis allow and encourage such useful collaboration. "Professional" development tools with access restrictions and approval processes kill him.

Answer 6

You can also combine approaches:

• Use the authoring wiki to attract more people just as technicians. Thus, for example, developers or support staff can easily participate.
• There are tools that convert from Wiki to at least DocBook, for example, the DocBook Wiki or my company Scroll Wiki Exporter (http://k15t.com/), which exports from Confluence to DocBook wiki and integrates DocBook style sheets for advanced customization ( see comment above), incl. RenderX XEP.

Hope this helps,

-Stefan