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

Posted by Andrew Piskorski on
Question 2, old vs. new style:

The new style is hideously awful, IMNSHO. All the big ugly button looking things are confusing. That's definitely the strong first impression, anyway! :) Overall, way too much chartjunk. Some of the other changes have merit, though.

Also, I suspect that numbering the steps may actually be counterproductive. These steps are not at all written in stone, and as the document changes all those numbers are going to change. Do we really want people to start referring to "problem in step 19" when the number 19 may well change the next time someone edits the document? On the other hand, for a given revision of the document, being able to refer to steps by numbers is kind of nice.

The attempt highlight the nouns in long lists of instructions like "check Editors", "uncheck Web Server" seems like a good idea, but the strong dark gray color isn't the best choice for this. Light gray should do the trick.

Also, I hope all the special markup is being done with some kind of stylesheet so e.g. the "draw attention to this text" background color can be easily tweaked?

In the old style, I also don't like the dark gray backgrounds very much. Too visually jarring. Backgrounds around all the shell commands are fine, but I'd suggest a much lighter gray color.