Forum OpenACS Development: Re: 4.6.x Documentation; Documentation formatting

Collapse
Posted by Roberto Mello on
Hi Joel,

Terrific work you've been doing.

I don't think a tutorial should be part of the Installation documents, because, well, it's not necessary for installation. If you already have OpenACS installed (say, from your distribution's install process, it may happen in the future), how would you know there's a tutorial in the installation docs?

The new style, while adding some enhancements, is too muddled for me. Too many colors, button-looking things that are not buttons, bright green on black text that looks like my ancient PC XT terminal.

I especially dislike the huge screens where you just have a long stream of commands for which the user is given no clue what they are for. Is the user supposed to just trust us? Or we could educate the user and let him/her know why we are suggesting him/her to run the next few commands?

For question 1, the longer release notes are only on openacs.org. I posted about it on a thread a while ago. OpenACS 4.6 was released without much fanfare, and wrote the longer release notes after the fact, so I couldn't just add to the Docbook sources and regenerate.

For question 3, cut-and-pasting is good, but I would personally never copy and paste more than a couple lines. In the example you posted, you have a screen full of commands. One can't tell where one set of commands ends and the other starts, and why they are being run.

So if the screens for command copy-and-pasting are short and explained, then we should be ok.

-Roberto