Using Markup To Communicate

The advantages of semantic markup are getting popular. I see that more developers are now getting involved in discussions and realize its need. By conveying the meaning and intent, semantic markup can help machines understand the context better.

During one of the Web projects I realized that semantic markup can also be an excellent communication tool within the team. Especially so for developers and designers. In past I have tried various methods, but using markup for communication seems to hold an edge over others. Note that by semantic, I do not mean using only the appropriate HTML elements, but using meaning CSS class and ID names.

Not a Wireframe

Of course, wireframe diagrams are a known technique to express the layout ideas. However this is more than that.

One of the early steps in a Web project are content identification, content design, content prioritization and classification. You might know them by some other names, but they convey crux of the matter. What is the best way for capturing and then documenting this design so that other team members can understand this? I think it is the markup.

Raw Markup

Unlike the wireframe this is raw markup, without any element of visual representation.

Look at the following example code:

<div id="content">
    <div id="primary">
        <div class="article">
            <p class="author"></p>
            <p class="excerpt"></p>
            <div class="article-body"></div>
            <p class="categories"></p>
    <div id="secondary">
        <ul id="sub-nav">

This code represents more than just the HTML elements. It informs rest of the team about the intent and design.

  • It conveys the content structure, e.g., here an article is composed of a title, the author, the excerpt and the article body.
  • The order in which the content is loaded is a good indication of the priority.
  • CSS class and ID names like primary and secondary do an efficient job of grouping content by the priority.
  • Using appropriate HTML elements, like h1 or h2 for the article title conveys its importance and significance.
  • It conveys the intended taxonomy and classification system.
  • It captures organization of the web page.
  • It focuses only on the content, not on the styles, and eventually helps in creating efficient CSS code.

All these together present the entire context to the code reader, which is what a team member is trying to capture in the documentation. Of course, you can leverage the HTML comments to add your own notes in the markup.

There are more benefits to this. The markup was work as a founding artefact of your process. You can also use corresponding directory hierarchy to simulate effect of your URL design.


There are some things that you should be careful of though. It is important to keep the markup raw and use it to represent only the content, without any element of visual style. Also, you might end up creating multiple HTML documents for every different context in your application. And the most critical one is that every team member should be conversant with HTML. If not, this can turn into a disaster.


HTML markup can be effectively used to keep the team on common ground. Its ability to represent the content structure and metadata lets us represent meaningful contexts. It also saves us time as you use the medium of delivery to document the design.

It is quite possible that you might be already practising this. Or, on the other hand you might find this extremely frivolous. I have surely benefited from using HTML to communicate with rest of the team, though some of my thoughts are still too abstract. Either way, feel free to comment on this.

Discussion [Participate or Link]

  1. Rohit said:

    At first I was a bit apprehensive about semantic markup. I have no idea why because it really makes sense. I agree that as a communication tool it is really helpful. And maybe it’s possible to write some script to parse a HTML document and present the markup in a human readable format for those who are not conversant with HTML ?

  2. Rohit said:

    On a side note – What plugin are you using for the comment filtering and rating ?

  3. Abhijit Nadgouda said:

    Rohit, semantic markup can help machines understand a lot of stuff, improving the possibility of automation.

    I use the SezWho plugin in the comments section here.

Say your thought!

If you want to use HTML you can use these tags: <a>, <em>, <strong>, <abbr>, <code>, <blockquote>. Closing the tags will be appreciated as this site uses valid XHTML.



Abhijit Nadgouda
iface Consulting
+91 9819820312
My bookmarks


This is the weblog of Abhijit Nadgouda where he writes down his thoughts on software development and related topics. You are invited to subscribe to the feed to stay updated or check out more subscription options. Or you can choose to browse by one of the topics.