12 July 2009

java.sun.com - improve online readability

Since I read a lot of Sun Java development documentation online, here is a more readable style. I only applied a small number of changes to avoid accidentally screwing up the site's presentation:

  1. Set text columns' maximum width to 30em. Elements which may be naturally wide, such as <img> (for images) and <pre> (for sample code), are not affected. Text is easier to scan if the columns aren't too wide.
  2. Set font family in <code> and <pre> (usually code samples) from Courier to Consolas or Courier New. Courier characters don't seem to get aliased (right term?) properly and look broken up on my notebook screen. Does anyone else have this problem? I chose Consolas because it matches the font I use in my IDEs sessions, and Courier New as a second choice because if Consolas is not available.
  3. Set <pre> background from gray to transparent. Sun marks up code samples in different ways, so it doesn't work in all pages.

Sun does not mark up all text in tags. For example, in javax.sql package summary, the text that follows <h2> headings cannot be styled since CSS cannot select text nodes. Might check if this a limitation of javadoc or whether API documentation writers have to explicitly mark up their paragraphs in <p> tags.