Design Guide or HTML Markup Guide

At a recent project, there was a requirement to describe the CSS used on a site, as a documentation, other developers could use. We decided to go a bit further — not only documenting the CSS classes — but making a guide that developers could find easy to use. Also we wanted developers with little or no CSS knowledge to be able to use the guide.

The usual design guide that dictates colors for headings, which images to use for bullet lists, margins between elements, line-heights, etc. When it comes to implementing the actual markup, the usual design guide is no help for developers when the first page is up on the website.

An HTML Guide has the following advantages over a traditional design guide:

  • Developers can focus on business logic.
  • No knowledge of CSS required for web developers. Experts took care of CSS, browser bugs, aligning pixels, etc.
  • Testing can be less thorough on other browsers once the initial work is done.
  • Service providers can save money as one portlet/webpart can integrate into many portals *)

*)  over time as a common format emerge on several portals.

It is my hope that we can use examples like this to make development of public applications cheaper and more consistent.

Here is the HTML guide we made in Capgemini recently in collaboration with Erhvervs- & Selskabsstyrelsen (Danish Commerce and Companies Agency) (the guide is in Danish)

HTML markup description

Each element contains of an HTML example (not an image, but rendered HTML based on current CSS):


And then there is the corresponding HTML markup for creating that particular example:


Examples of HTML Markup guides

List with examples that are public available on the web

  • (Denmark): HTML Guide (in Danish) is the Danish public portal for everything companies need to interact with public authorities.
    Technical note: Still has minor browser rendering issues that we are looking into. HTML is as clean as the graphical design allows.
  • TDC (Denmark): Metaform guide (in Danish)
    TDC, the big Danish telco has a similar guide, also public available.
    Technical note: Suffers from tag soup, but otherwise is very comprehensive.

I will update this list if you know of any examples that you know of. If possible, provide all the following  information:

  • Name or domain of the guide
  • Language
  • URL for public version of the guide
  • Short description of guide scope or content
  • Corresponding graphical design guide (if applicable)
  • Technical note

Technorati Tags: , , , , , , , , ,

10 Responses to “Design Guide or HTML Markup Guide”

  1. Charlie Says:

    Amazing article, shame the guides aren’t in english!
    Anyway, thank you for the article.

  2. Dave Says:

    Is there a difference between these guides and a comprehensive design document? I might be confused because I use the phrase “web developer” to refer to people involved in all parts of the process of creating a web presence (that is, the person who designs the visual look, the person who writes HTML and CSS, the people who write client-side and server-side code, etc), and I’m realizing that you might be using it in a more specific way.

  3. Robert S. Says:

    En takk fra Norge :)

  4. Medical Staffing Software Says:

    Jesper, is there any way we can get this guide in English?

  5. tickets Says:

    Nice post and it would be great if the guides ware in English.

  6. Web hosting Says:

    I would be interested in seeing the web design guide in english also. I am sure alot of people would like to be able to read it over.

  7. Webmaster tips Says:

    I’ve got a friend at work who is Danish ;) I’ll have to get him to translate.

  8. James McGinley Says:

    Guide can be translated by viewing e.g. with Google Translate

  9. Brian Nielsen Says:

    Hi Jesper

    The guide has moved to it’s (correct) url:

    please update.

    Brgds Brian

  10. Jesper Rønn-Jensen Says:

    Brian, thanks a lot for pointing out the new location of the Virk HTML guide. I have now updated the links.