Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
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 –  George Oct 27 '11 at 18:31

4 Answers 4

up vote 5 down vote accepted

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.

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

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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