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

Posted by Torben Brosten on
Hi Joel,

The current style has evolved from input from the community. There are basic reasons for keeping it similar. Does it really have to change much?

For instance:

1. Greys (and colors near grey) work best because they are color neutral. That is, they work for people and equipment that are color blind or where a primary color does not work.

2. Italics work best in font sizes that are larger than standard, again because readibility.

3. Sans-serif fonts are generally easier to read.

4. The current doc style is fairly browser display tolerant.

I think there has been some criticism about the use of background colors for highlighting.

You could experiment by making a light grey backround around the outer document boundaries (perhaps a lighter grey background  for the document background) and white to highlight the background of "screen shots" etc.  This would provide visual highlights and may reduce eye strain for those who experience difficulty reading high-contrast screens. However, large grey backgrounds may be a problem if  some printers print the background color. =(

Thick (grey) borders may be enough for highlighting blocks of text, so that varying the background color becomes unneccessary.

Posted by Joel Aufrecht on
The latest evolution of the formatting is visibile here This section is complete, and shows the following:
  • All of the button and label markup is gone except for courier font
  • shaded background is used in blocks to indicate shells and program listings
  • The body font is a surprise. I've actually left it sans-serif through all versions but it's coming out serif anyway. Feedback welcome as I sort through browser settings, site-wide stylesheets, etc, to understand this phenomenon.
  • Bold is used only for text that you enter into the computer, and in headings which are also in a larger font.
  • I've left the "replaceable" text red, because it's also italic and a bit bigger than surrounding text, so it doesn't just rely on color. It's the only italic used.
  • Shell commands are duplicated to make cut-paste easier.