[Contentless] ITT you post right now [ASAP] your current thought [Brains][Thinking][Personal][#30] (999)

569 Name: (*゚ー゚) : 1993-09-9145 03:31

>>563
Use whatever you want, but more importantly make sure to put a bunch of typical usage examples at the top of every page. I always scroll straight to the examples in documentation and I'm sure I'm not the only one.

570 Name: (*゚ー゚) : 1993-09-9145 06:37

>>563
GNU info, so that it technically exists but basically nobody will ever find it and even if they do they'll give up before the interface takes its toll on their sanity.

571 Name: (*゚ー゚) : 1993-09-9145 06:42

>>563
GNU info, so that it technically exists but basically nobody will ever find it, and even if they do they'll give up before it takes its toll on their sanity, and even if they convert it to HTML the pages will be produced separately making it more difficult than necessary to navigate and search, and even if they convert it to a single HTML page it will be so long that aw fuck this this is why nobody writes good autotools scripts

576 Name: (*゚ー゚) : 1993-09-9145 08:18

>>563
If the audience is non-technical, I either use plaintext (treated as plaintext) or LaTeX, with plaintext preferred. This will ensure that documentation is either simple enough that it can be read quickly, or detailed enough to be reassuring.

IMHO, the benefits of almost-plaintext formats are extremely slight, and overshadowed by the threat that it might get overcomplicated to the point that it requires a browser to view.

If the audience is technical, typing "man foo" is more direct than searching the web for "foo documentation -bar -baz" or hunting through /usr/share for a README: the brain has to go through fewer context switches between "How do I work the damn thing again" and "I am now learning how to work the damn thing". mdoc.samples(7) is helpful.

Also what >>569 said.

582 Name: (*゚ー゚) : 1993-09-9145 21:13

>>573
I prematurely hit send on accident, not sure how, I do have phantom clicks and keystrokes on this turrible hardware. So now the world gets to laugh at my foolishness (but 'tis better, I find, to be laugh'd at than y-wept).

I am slightly serious about the autotools documentation, though, it's not like it's great and there are corner cases it won't help you with, but it probably tells what you want from an 80-20 perspective if only you could actually not have navigation issues in the way and if only it weren't a "do it this way or weird shit will happen" kind of suite.

This thread has been closed. You cannot post in this thread any longer.