Best format for writing software documentation?

  • Thread starter Thread starter Iain Cheyne
  • Start date Start date
I

Iain Cheyne

I want to write a short manual for an open-source utility. Which format
should I use?

Although plain text is the simplest and most generic, it is too ugly and
does not support hyperlinking, so I have ruled it out. PDF is also out, as
it for printing, rather than online viewing. I'm mainly considering html,
Html-help or Winhelp, but there might be other formats that are better that
I'm not aware of. I want something simple, easy and with nice formatting
and hyperlinking.

TIA
 
Iain said:
Although plain text is the simplest and most generic, it is too ugly and
does not support hyperlinking, so I have ruled it out. PDF is also out, as
it for printing, rather than online viewing. I'm mainly considering html,
Html-help or Winhelp, but there might be other formats that are better that
I'm not aware of. I want something simple, easy and with nice formatting
and hyperlinking.
Click to expand...

The info format allows hyperlinking in a text file. It's similar to man but
with that capability. I don't know much about it. If you have to have
GUI, it would be out of the running, but I don't know how you weight the
cosmetic versus functional components of your first sentence.
 
I want to write a short manual for an open-source utility. Which format
should I use?
Click to expand...

Since you want to include hyperlinks, a very basic HTML page should do
fine. You don't really need to specify format, just use
header/title/body with line breaks for paragraphs. You might want to
use a few meta tags for identification of the utility's home page,
your name, etc.
 
Iain Cheyne <[email protected]> wrote:
Click to expand...
I want to write a short manual for an open-source utility. Which format
should I use?
Click to expand...
Although plain text is the simplest and most generic, it is too ugly and
does not support hyperlinking, so I have ruled it out. PDF is also out, as
it for printing, rather than online viewing. I'm mainly considering html,
Html-help or Winhelp, but there might be other formats that are better that
I'm not aware of. I want something simple, easy and with nice formatting
and hyperlinking.
Click to expand...

Call me old fashioned, but I prefer plain text, along with whichever
other method you choose that allows for linking. This is assuming that
this is documentation to be included with the program.
 
Call me old fashioned, but I prefer plain text, along with whichever
other method you choose that allows for linking. This is assuming that
this is documentation to be included with the program.
Click to expand...

Iain - I think you should read this website here,
http://www.the-office.com/lunchbook/overview.htm , I found it about a
month back and couldn't agree more with the sentiments about PDF and
other standards for computer reading material.

As for the format, HTML is the best from what you've mentioned, at
least it's cross platform, can be viewed in full screen and can be to
a degree self formatting. Winhelp isn't really in the spirit of open
source since Microsoft didn't release to the public how it's standard
works for a long time, if they did ever. The newer format is actually
compressed HTML or something isn't it ! It's a pity to loose the find
function of that, perhaps theres some way to download a little
javascript or something which does much the same job and add it to the
HTML, I've seen that done on cover discs of magazines before.
 
Iain said:
I want to write a short manual for an open-source utility. Which format
should I use?

Although plain text is the simplest and most generic, it is too ugly and
does not support hyperlinking, so I have ruled it out. PDF is also out, as
it for printing, rather than online viewing. I'm mainly considering html,
Html-help or Winhelp, but there might be other formats that are better that
I'm not aware of. I want something simple, easy and with nice formatting
and hyperlinking.
Click to expand...

I would recommend HTML. It's a standard, it runs on any platform. You
can easily put it on your web page so people interested in your
utility can peruse the help before downloading your program. And other
people can easily edit it -- since your program is open source, why
not make the documentation that way too.

Note that HTMLHelp is simply a compressed form of HTML, so you get
that easily once you have written the Html. The advantage of HTMLHelp
is that it is 1 file, instead of an entire directory structure. And it
is smaller. The disadvantage is that it is proprietary and windows
only. So, how about distributing HTMLHelp with the windows executable,
and plain html with the source distribution.

Terry
 
As for the format, HTML is the best from what you've mentioned, at
least it's cross platform, can be viewed in full screen and can be to
a degree self formatting. Winhelp isn't really in the spirit of open
source since Microsoft didn't release to the public how it's standard
works for a long time, if they did ever. The newer format is actually
compressed HTML or something isn't it ! It's a pity to loose the find
function of that, perhaps theres some way to download a little
javascript or something which does much the same job and add it to the
HTML, I've seen that done on cover discs of magazines before.
Click to expand...
Compiled html. Basically a lot of html files packaged together along with
images etc. Build with html help workshop from download.com
 
Terry Orchard said:
SNIP>
Note that HTMLHelp is simply a compressed form of HTML, so you get
that easily once you have written the Html. The advantage of HTMLHelp
Click to expand...
<SNIP>

Actually it's compiled HTML, more than just compressed.
HK
 
Iain Cheyne said:
I want to write a short manual for an open-source utility. Which format
should I use?

Although plain text is the simplest and most generic, it is too ugly and
does not support hyperlinking, so I have ruled it out. PDF is also out, as
it for printing, rather than online viewing. I'm mainly considering html,
Html-help or Winhelp, but there might be other formats that are better that
I'm not aware of. I want something simple, easy and with nice formatting
and hyperlinking.
Click to expand...

Ultimately it depends on what you are trying to accomplish with the help. If
it's strictly a Windows program, the best is either of the Windows help
formats. I prefer to use Winhelp .hlp files as they are easier to include
and reference in VB, which I use. I have used HTMLhelp .chm files, they are
easier to build, but harder to implement in VB. Since most of my projects
are reasonably simple, a lot of times I use a seperate form and write the
help there, of course you lose the F1 call help feature then. Either way
that is the best IMO for the Windows platform. For cross platform, I'd use
either HTML or PDF, but IMO, one's as bad as the other. Both require extra
support programs, Acrobat reader or a browser, and neither can be fully
integrated with the program.
For what its worth.
HK
 
how about distributing HTMLHelp with the windows executable,
and plain html with the source distribution.
Click to expand...

Thanks to everyone for the advice, this seems to be the best option.
 
I'd be interested to learn more about this. I found very little with a
Google search - what a terrible name for a software format!
Click to expand...

info is the command that brings up the documentation. I probably
shouldn't have called it "the info format". I should've said whatever
format info opens. It's an inhancement to man, which did not allow
linking. Examples:

info mozilla

man mozilla
Hyperlinking and formatting are important to aid usability in this
case.
Click to expand...

I asked about cosmetics. Because you said someting or other was "ugly",
and I read that to mean "a no-go". so I was asking if a good format
that you considered "ugly" would be dismissed regardless of
functionality.
 
On Fri, 18 Jul 2003 08:33:23 +0100, msd13

As for the format, HTML is the best from what you've mentioned, at
least it's cross platform, can be viewed in full screen and can be to
a degree self formatting.
Click to expand...

< snip >

My preference is the standard "Help" format. No need to open
another program (browser). Added to that a lot of idiots who do
HTML help files don't include it with the download. Rather
irritating if one wants "help" and they aren't online.

Regards, John.

--
****************************************************
,-._|\ (A.C.F FAQ) http://clients.net2000.com.au/~johnf/faq.html
/ Oz \ John Fitzsimons - Melbourne, Australia.
\_,--.x/ http://www.aspects.org.au/index.htm
v http://clients.net2000.com.au/~johnf/
 
On Fri, 18 Jul 2003 08:33:23 +0100, msd13



< snip >

My preference is the standard "Help" format. No need to open
another program (browser). Added to that a lot of idiots who do
HTML help files don't include it with the download. Rather
irritating if one wants "help" and they aren't online.
Click to expand...

You didn't mention if or not you think windows help format (.hlp or
..chm) is the best thing to include alongside open source software. I
agree with what you say about online html help, it's not the best. I
think I'd like something which is simply like a full screen notepad
with two pages which supports hyperlinks and some easy to use e-book
reader kind of contols, but it's not a standard so I thought HTML
might be closest to that. Regardless it looks like the OP has opted
for both HTML and CHM(?) format, CHM with the application and HTML
with the source... seems fair, except that CHM usually implies that
you must have IE installed and Mozilla is open source.
 
Back
Top