Five questions to ask before distributing content as HTML
HTML5! Mobile! Responsive design!
It’s easy to get distracted by sparkly buzzwords when you investigate distributing your technical content as HTML. Instead, focus on a few basic but essential questions:
(flickr: woodleywonderworks)
1. Are there are corporate standards for web page design?
If your company already publishes web content, it’s likely there are guidelines for how HTML content should be coded. Get those guidelines, review them, and use them during your design phase. Those of us in tech comm are accustomed to following style guides, right?
2. What are the primary browsers used by those consuming information?
Your company’s web team can tell you which browsers your company’s site is primarily supporting. (In a perfect world, company web sites would work flawlessly across all browsers, but reality has other ideas.) Don’t assume your readers will use your personal browser of choice, and some of them may work in an environment with locked-down machines and slow software upgrades. You may have no use for Internet Explorer 7, but maybe your readers aren’t so lucky.
Consider the abilities and limitations of users’ primary browsers while developing your specs for HTML, but your design (and eventual testing of HTML content) should extend to other browsers as well.
There’s a lot of chatter about delivering web content to mobile devices these days. Your existing web infrastructure (assuming there is one) may not support mobile display, and such support may not be coming any time soon. Also, those neat-o features of HTML5 you read about may not work in an older browser you need to support.
3. Is a search engine already integrated into the web site? Can new content be integrated into it?
If there is a search engine in place, find out if you can use it for your content. Also, will it allow users to search just the technical content and to search across all company information? Strong search capability is critical to the usefulness of your web content. Without search, your web content will provide only a fraction of the value that it could—be prepared to license and implement a search engine.
4. How should repeated elements, such as navigation bars, the company logo, and footers, be implemented?
To keep file sizes down, one common technique is to link in repeated elements (such as a navigation bar) so that it’s not actually stored in every web page. Your design should conform to the established approach.
In some cases, your web team needs HTML fragments without root tagging (such as the top-level <html> element) because they will wrap your content to add the root tags, references to the navigation bar, and so on.
5. Do you have web-ready images?
If you’ve been cranking out printed books and PDF files, your illustrations, screen shots, and so on, may not be in formats that web browsers understand (PNG, JPEG, and GIF, for example). You’ll need to develop strategies for converting images and including web-ready versions.
There are many other considerations when you’re distributing technical content as HTML; my list certainly isn’t exhaustive. Please share your own wisdom in the comments below. Horror stories are always welcome!
About the author
Leigh White
Hi Alan,
An issue that we’ve bumped up against when distributing application help as HTML is whether the help is installed locally on machines or accessed via a web server. Many older applications were designed to access help locally, which can limit the functionality available via scripts, Java, etc. HTML-based help generated through RoboHelp or Flare (for example) often has proprietary ways of replicating web-server-based functionality. This functionality is usually lacking (natively) in help generated via the Open Toolkit or related methods and it can be difficult to find a way to replicate it in a non-web-server environment.
Alan Pringle
Excellent point, Leigh, and a timely one. We’re about to start another web help project, so thanks for the reminder!