[OpenAFS] Documentation project comments

[Robert Banz]

Esther Filderman wrote:
> On 6/10/05, ted creedon <tcreedon@easystreet.com> wrote:
> 
>>For what its worth, I think html documentation with hyperlinks is not the
>>best way to go. It just happened to get done first on the second round of
>>conversions.
> 
> 
> Yes, you've made your bias clear since you started this. While I
> sincerely appreciate your effort, we MUST have documentation that's
> available online.  Requiring people to download giant postscript or
> pdf files to look up one command is ludicrious.
> 
> Making things look pretty is fine, but they also have to be usable. 
> In the end, HTML is likely going to be the most used.

Arr.  Putting documentation in a format that is conducive to easy 
editing, and it's structure, and having that align with its expected 
(and unexpected) publication vectors is a tough one.

Formats that are "easy" to take and publish to multiple vectors, such as 
web and print, typically suck to write in.  DocBook is one of those. 
You have to really dig your SGML.  On the other hand, there are some 
WYSIWYG-ish editors for those of use that have gotten tired of seeing 
your structure descriptors -- or, who's '<' and '>' keys on their 
keyboards are completely worn down...

Now...what to do, what to do...

-rob