2

I want to make User Manual/Help to my program. I found two good ways - XML or HTML - which should I use and why?

I know how to do it in html (I know how to use js, css and such) but in XML it's harder (or I imagine?)

anyway which way should I choose and why?...

Edit:

There's one important thing I forgot to mention: I need it for the army, I can make it only on army's computer and I cannot install anything you said. I can use notepad and that's it.

1
  • I'm pretty sure that is a heavy restriction. I'm sure you'll manage to install a DocBook writer software for it. If not, the quality of your work (I'm not speaking about content) will drop substantially. After a few pages you WILL lose track of patterns and specifics that you may hve defined for the document Oct 27, 2011 at 18:31

4 Answers 4

5

Actually, I would go for both.

We are writing big manuals for a military system and DocBook with it's transformations possibilities is great. Don't create your own schema, use the comprehensive one that DocBook has and export to HTML, PDF, Latex, etc.

Storing things in DocBook also has the tremendous advantage that it's just plain text, meaning that you can sensible store it in CVS, associated bugtracker tickets to it, etc. In the long run, for big manuals, this is just the way to go.

It works great.

3
  • +1, and would give more if I could. Docbook is really the easy way to go here.
    – thiton
    Oct 27, 2011 at 16:27
  • That's what we use here too, to generate both a PDF manual and an integrated JavaHelp manual.
    – barjak
    Oct 27, 2011 at 16:44
  • If you are doing an XML based format, Docbook is the only way to go.
    – user7519
    Oct 27, 2011 at 17:05
0

XML will let you define custom elements that you can use transform into HTML using XSLT (XSLT is used to transform XML data from one format to another). This is more flexible, but also more work.

For example: If you go the XML route, you could define new elements in an XSD (XSD is where you can define new elements) and your document could be written like this:

<HelpHeader>Ron's Help manual</HelpHeader>
<Warning level="5">Not to be taken internally!!</Warning>
<HelpBody>Welcome to the Help Manual!
        <HelpSidebar>I hope this documen is very helpful to you<HelpSidebar/>
</HelpBody>

This might make it easier to write the document as the elements are closer to the document you're writing. You must then use XSLT to transform the document into HTML (and I think you can include CSS and maybe JavaScript here as well?), which might be a lot of work.

One advantage of going the XML route is that if you ever decide to change the layout/look-and-feel, you don't change the content of your XML file, you change the XML-to-HTML translations in the XSL file. This way the content is preserved and huge and sweeping style changes can be made quite easily. This is a big bonus when the style changes are relatively small, but there are hundreds of HTML files. You can make one change in the XSL, and regenerate the HTML with a single button-click! No one wants to manually reapply HTML changes to all those files.

0

I'm going to suggest using Markdown because you can write simple text and have it converted to HTML for you. You can use WriteMonkey to write text using Markdown syntax and export it to HTML. For simple documentation, this may be all you need.

0

If you like XML then use Docbook then you can generate, HTML, PDF, CHM or whatever from it.

Other alternatives to XML that are easy to generate various outputs are Markdown, Textile and other Wiki-like syntax driven markup languages.

You should really focus on something that can target mutliple formats for final output such as ePub as well.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.