For writing documentation, I would only consider three formats: plain text, LaTeX, and POD.

Plain text has two huge advantages. First, it's simple, you don't need any special tools to read or write it. WYSIWYG even in the simplest text editor, and it causes no problem for the blind (something I care a lot about). Second avantage is that it is nowadays about the only format that's cross platform. I can read plain text documents that were created more than 30 years ago, and I have no doubt that a plain text document created today will be readable 30 years from now. RFC's have been written in plain text since RFC 1, and they will be written in plain text for the foreseeable future. What's good enough for RFC's is certainly good enough for my documentation. Another advantage is that plain text is so "plain", it really lets you focus on the content.

LaTeX is great. It allows you to separate content from presentation by using stylesheets, without prohibiting you from doing complicated stuff. There are lots of free packages available enabling you to create sophisticated documents easily. It's the Perl of documentation languages, but with less ugliness. For documentation in dead tree format, it would be my first choice.

I only use POD for documenting Perl programs, and mainly because it's common to do. When installing stuff with CPAN, documentation gets automatically extracted. But the markup of POD is minimal, it doesn't give that much more than plain text is giving you. The existance of a pod2man, and the non-existance of text2man makes that I still use POD.

Abigail

In reply to Re: What's the best plain Documentation format? by Abigail-II
in thread What's the best plain Documentation format? by gmpassos

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.