Building HTML and CSS With Kindness: Documentation II.
Copy this link for a short URLHTML & CSS are an exception in the documentation world. The reason for this is quite simple. HTML & CSS are a front-end language that already have some inherent properties of documentation.
Take for example this little slice of code-pie:
#navigation {display: inline}
<ul id="navigation">
The relationship is clear and easy to understand but how do you make markup so understandable it’s like free-brain day at the knowledge store?
Semantic Markup and You!!
You’ve heard it thousands of times that semantic markup is important and I don’t want to bore you to tears. No, I want to bore you to manic-depression. Good semantic markup is the cornerstone of writing documentation in HTML. The language of HTML is structure-based, and since there is very little functionality, it’s easy to understand.1
Say we have a very basic body element with template code.
<body>
<div id="wrapper">
<h1 id="branding"><img src="logo.jpg" alt="Mordor" title="Mordor" /></h1>
<ul id="nav">
<li><a href="mordor.html">Things to do</a></li>
<li><a href="getintouch.html">Contact</a></li>
<li><a href="biography.html">History</a></li>
</ul>
<div id="content">
<p>Welcome to Mordor: A Traveller Oasis where you can enjoy all that our magical kingdom has for you to offer</p>
<p>There are many fun things for you to do, take for example:</p>
<ul>
<li><strong>Slay the Dark Lord Sauron at Mt. Doom</strong>: Finally a place where you can murder our wonderful overlord again and again.</li>
<li><strong>Be Betrayed!</strong>:Be convinced by a hunched, scary, murderous half-hobbit with lung cancer to kill your best friend.</li>
<li><strong>Send out the drones!</strong>: Yes you too can relive the historic battle of the White Castle where Saurons army victoriously slayed a lot of humans. Take your photo in front of a Mission Accomplished banner.</li>
</ul>
<p>... and much more! Get in touch with one of our helpful travel agents today:<img class="orc" src="images/orc-eating-human-baby.jpg" /></p>
</div>
</div>
</body>
This is great code. I know, because I wrote it and I’m wearing a god-damn beard on this site. You can understand the structure easily and semantically it makes sense. There’s not much room for documentation if it’s clear what you’re doing. The strong tags may not be very semantic, but in the context they make sense.
Indent.
Good indentation, needs to happen. For each container (e.g. div) hit enter and 2-4 spaces or 1 tab. Variate to personal taste, but be wary of monitor-width. You have no choice in the matter.
Cuttin’
Modern development however, involves chopping off pieces of these templates into partials. Therefore, a little preparation can make for a nice document.
<body>
<div id="wrapper">
<!-- Navigation & Branding -->
<h1 id="branding"><img src="logo.jpg" alt="Mordor" title="Mordor" /></h1>
<ul id="nav">
<li><a href="mordor.html">Things to do</a></li>
<li><a href="getintouch.html">Contact</a></li>
<li><a href="biography.html">History</a>
</ul>
<!-- end -->
<div id="content">
<!-- Begin Entry Content -->
<p>Welcome to Mordor: A Traveller Oasis where you can enjoy all that our magical kingdom has for you to offer</p>
<p>There are many fun things for you to do, take for example:</p>
<ul>
<li><strong>Slay the Dark Lord Sauron at Mt. Doom</strong>: Finally a place where you can murder our wonderful overlord again and again.</li>
<li><strong>Be Betrayed!</strong>:Be convinced by a hunched, scary, murderous half-hobbit with lung cancer to kill your best friend.</li>
<li><strong>Send out the drones!</strong>: Yes you too can relive the historic battle of the White Castle where Saurons army victoriously slayed a lot of humans. Take your photo in front of a Mission Accomplished banner.</li>
</ul>
<p>... and much more! Get in touch with one of our helpful travel agents today:<img class="orc" src="images/orc-eating-human-baby.jpg" /></p>
<!-- end -->
</div> <!-- #content -->
</div> <!-- #wrapper -->
</body>
One of the more confusing aspects of long HTML templates or pages is which div is closing where. As the structure gets more and more complex, some comments at the end can help ease the pain of division.
Except…
Problems occur when modern browsers collide with modern design and extra markup must be added. While this is slowly becoming less and less prominent as browsers adapt CSS3 rules, one must alter structure to compensate. This is where HTML throws curve-balls and a little documentation is required.
If you’re using something like the Sliding Doors of CSS to make markup magic, let the reader know with a simple:
<!-- This badassss piece of work uses Sliding Doors II: http://www.alistapart.com/articles/slidingdoors2/ -->
Now the developer/user/code-thief, if they don’t understand the crazy markup you have slid into place, can go and reference A List Apart: seeing for themselves just what in Trogdor’s name you were thinking. It’s simple, doesn’t take up much space and will help them understand the CSS better when they need to re-write your crap code.
head
In the head tag I tend to comment off sections so people know what is what:
<!-- Metadata -->
<meta name='description' content='Happy Magic Fun Time is the home of Kenny Meyers, a very serious developer who writes in very serious tones about high priority, important matters.' />
<meta name='keywords' content='developer php expressionengine ruby rails blog training awesome kenny meyers kennymeyers codeIgniter' />
<meta name='robots' content='index,follow,archive' />
<link rel='schema.DC' href='http://purl.org/dc/elements/1.1/' />
<link rel='schema.DCTERMS' href='http://purl.org/dc/terms/' />
<meta name='DC.title' content='Happy Magic Fun Time' />
<meta name='DC.creator' content='Kenny Meyers' />
<meta name='DC.subject' content='developer php expressionengine ruby rails blog training awesome kenny meyers kennymeyers codeIgniter' />
<meta name='DC.description' content='Happy Magic Fun Time is the home of Kenny Meyers, a very serious developer who writes in very serious tones about high priority, important matters.' />
<link rel="shorturl" href="/u/0" />
<!-- Stylesheets -->
<link rel="stylesheet" href="/assets/css/screen.css" type="text/css" media="screen" />
<link rel="stylesheet" href="/assets/css/print.css" type="text/css" media="print" title="Print Stylesheet" charset="utf-8" />
<!-- jQuery Stylesheets -->
<link rel="stylesheet" type="text/css" href="/assets/js/lightbox/css/jquery.lightbox-0.5.css" media="screen" />
<!--[if IE]>
<link rel="stylesheet" href="/assets/css/ie.css" type="text/css" media="screen" />
<![endif]-->
<!-- jQuery -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
<script src="/mint/?js" type="text/javascript"></script><!-- Mint -->
<script src="/assets/js/lightbox/js/jquery.lightbox-0.5.min.js"></script>
<script src="/assets/js/hmft.js"></script>
<!-- Favicon & RSS -->
<link href="/favicon.ico" type="image/x-icon" rel="icon" />
<link href="/favicon.ico" type="image/x-icon" rel="shortcut icon" />
<link rel="alternate" type="application/rss+xml" href="http://feeds2.feedburner.com/hmftime" />
</head>
Cluttering up your markup with comments can quickly become unreadable, so make sure you choose wisely. Lest you end up mocked by an ancient Medieval Knight from The Last Crusade.
Are you there God? It’s me, CSS grouping
HTML documentation is easy and inherent. CSS documentation is where you’re going to run into trouble. Unlike template files, which are general so simple that many can pick up on it, CSS files can get wordy and normally singular to the site.
An unruly CSS file causes more trouble with website display only second to JavaScript functionality and Javadevelopers. It is therefore the cross we must bare for others to make it clean and organized.
Two problems. One… file
There are two methods of organization, each with its own type. The decision is subjective and if you’re working on a team, make it as a team.
Aforementioned problems:
- Do you use block-level style declarations or inline
- Do you organize it by element type or by page type
Again these are subjective, and I tend to favor the following.
For my style declarations I use inline styles. I find them more readable and more to my liking. They also take up less space but still give you a clear indication of what’s going on. This is completely to you and your team’s preference.
For my organization-style, I tend to organize the rules into commented-groups by template or view. I keep my generic styles on top (e.g. p {style: style-declaration}) and my more specific styles in groups that, as you scroll down, become more element-specific.
/* @group Generic Page Styles & Layout */
body {font: 14px 'Myriad Pro', 'Helvetica', 'Arial', sans-serif; background: #f4efe2 url(../images/background.jpg) top center fixed no-repeat;}
h1 {margin-bottom: 40px;} /* Logo */
#container {width: 950px; margin: 0 auto; padding: 0 5px 0 5px; position: relative;}
.center {margin: 0 auto;}
.left {float: left; margin: 0 10px 10px 0;}
.right {float: right; margin: 10px 0 0 10px;}
.text_center {text-align: center;}
.small {font-size: 10px;}
/* @end */
/* @group Content */
#content {width: 600px; float: left; margin-right: 70px; margin-bottom: 30px; margin-top: 0}
#content p, #content h3 {margin-bottom: 10px}
/* @end */
So you can see that even moving down the styles in a group, the specificity increases in power. I include comments that specify any odd outlier (e.g. /* Logo */ for the h1 element) just to be extra sensitive: for her pleasure.2
If I’m in the IE stylesheet, and I’m using a hack such as the Holly Hack, I note it next to the declaration.
ul {height: 1%} /* Holly Hack */
This provides a very simple framework for building CSS Stylesheets that isn’t horribly disorganized. If there’s a new template or page being built, I will create a new group.
CSSEdit has a great way of handling how these groups are managed and I can’t recommend it enough if you’re a Mac user. It displays groups as folders and is better than when you first saw the T-Rex in Jurassic Park.
And in the End, the love you make…
...is equal to the time you take to not screw over other devs. It’s important that you give, share and set standards. Writing dev-facing CSS and HTML code is not as complex as comments in JavaScript or PHP, but it’s important all the same.
With HTML & CSS, there is one rule: Good documentation is good organization. Use semantics and be bold.3
Have a frumptuous day, churtling in your joy.
1. Functionality as in a to call a function, much like get_up_get_on_up_like_a_sex_machine()
2. My sincerest apologies for this brief stint into amateur potty-talk, but I would be remiss if I didn’t grab at the chance to use one of my favorite taglines. It really works with anything and delivers maximum comedic effect.
3. strong
Integrity Section:
You can hire me for some sweet freelance. I'll also make fun of you for $10.
