Documentation as web sites

Those of us who write online documentation have an opportunity to move beyond the old book style of technical writing. Instead of writing books, we could start to think about whether we can present our documentation as web sites.

Instead of an opening page that has the date and a copyright notice (or whatever your HTML opens to), you could create a web page that is interesting and engaging, containing:

• A mix of types of information that draws people in and makes them want to read: a section on samples or case studies that are interesting to read through; a section of videos; and so on.
  
• Subtle but consistent and informative use of metaphor, such as visual clues that complement navigation.
  
• Quality art/photos that create a mood (not icons or clip art).
  
• Playfulness, creativity, and a focus on making people want to read the site.

When architecting doc web sites, I'd like to see writers considering good web site design principles. For example:

• Creating headings that use dynamic action verbs; headings formed as questions; and intriguing section titles such as "Try me".
  
• Chunking content based on reader needs (such as new/not-new, inexperienced/experienced, or UI/API), rather than organization by typical content-based chapters.
  
• Providing a seamless mix of content from all sources.

I haven't mentioned providing the opportunity for reader participation and feedback only because I think we're geting a good handle on that in the industry, and it's a given.

It's vital to note that none of this should be frivolous or have a marketing bent. None of this should feel like a bells-and-whistles approach. All of the effort should be focused on helping readers absorb and retain information.

The site should first and foremost be informative, and it should contain reference materials, numbered lists, detailed conceptual info... but content should not be included just because it covers everything that could be said. Content should be included only when it's needed by readers.

The whole thing could be written in topics and single-sourced into both the web site and a more standard structure in a PDF. Single-sourcing could also be used to repeat content in more than one place on the site.

There are problems to overcome with tools and with browser support. There are possible pitfalls: we don't want to create something that's busy, causes navigation problems, or is annoying. But I think this could be done.