When you write documentation, whether or not that is for an open supply undertaking or a technical writing undertaking, it’s best to have two targets: The doc must be written nicely, and the doc must be simple to learn. The first is addressed by clear writing abilities and technical modifying. The second may be addressed with just a few easy modifications to an HTML doc.
HyperText Markup Language, or HTML, is the spine of the web. Since the daybreak of the “World Wide Web” in 1994, each net browser makes use of HTML to show paperwork and web sites. And for nearly as lengthy, HTML has supported the stylesheet, a particular addition to an HTML doc that defines how the textual content ought to seem on the display screen.
You can write undertaking documentation in plain HTML, and that will get the job achieved. However, plain HTML styling might really feel a little bit spartan. Instead, attempt including just a few easy types to an HTML doc so as to add a little bit pizzazz to documentation, and make your paperwork clearer and simpler to learn.
Defining an HTML doc
Let’s begin with a plain HTML doc and discover learn how to add types to it. An empty HTML doc accommodates the
You can outline a clean web page with this HTML code:
In one other article about Writing project documentation in HTML, I up to date a Readme file from an open supply board recreation from plain textual content to an HTML doc, utilizing just a few primary HTML tags like
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The recreation will routinely "throw" the throwing sticks
for you, and show the leads to the lower-right nook
of the display screen.</p>
<p>If the "throw" is zero, then you definately lose your flip.</p>
<p>When it is your flip, the sport will routinely choose
your first piece on the board. You might or will not be
capable of make a transfer with this piece, so choose your piece
to maneuver, and hit <i>Space</i> (or <i>Enter</i>) to maneuver
it. You can choose utilizing a number of completely different strategies:</p>
<ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>proper</i> to
navigate to a selected sq..</li>
<li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left"
and "right" on the board. Note that this may routinely
comply with the "backwards S" form of the board.</li>
<li><em>Tab</em> to pick your subsequent piece on the
board.</li>
</ul>
<p>To give up the sport at any time, press <b>Q</b> (uppercase
Q) or hit <i>Esc</i>, and the sport will immediate if you would like
to forfeit the sport.</p>
<p>You win if you happen to transfer all your items off the board
earlier than your opponent. It takes a mixture of luck and
technique!</p>
</body>
</html>
This HTML doc demonstrates just a few widespread block and inline parts utilized by technical writers who write with HTML. Block parts outline a rectangle round textual content. Paragraphs and headings are examples of block parts, as a result of they lengthen from the left to the best edges of the doc. For instance,
You can apply direct styling to this doc to vary the font, colours, and different textual content types, however a extra environment friendly method to modify the doc’s look is to use a stylesheet to the doc itself. You can try this within the
Defining types
Since you are simply beginning to find out about stylesheets, let’s show a primary type: background shade. I like to start out with the background shade as a result of it helps to show block and inline parts. Let’s apply a considerably gaudy stylesheet that units a mild blue background shade for all
You outline these utilizing types within the factor { type; type; type; ... } and makes use of curly braces to group collectively a number of textual content types right into a single definition.
Note that every type ends with a semicolon.
If you view this HTML doc in an online browser, you’ll be able to see how the
(Jim Hall, CC BY-SA 4.0)
Applying types
You can use types to make this Readme doc simpler to learn. You’re simply beginning to find out about types, you will stick to some easy type parts:
- background-color to set the background shade
- shade to set the textual content shade
- font-family to make use of a special textual content font
- margin-top so as to add house above a component
- margin-bottom so as to add house under a component
- text-align to vary how the textual content is displayed, akin to to the left, to the best, or centered
Let’s begin over together with your stylesheet and apply these new types to your doc. To start, use a extra pleasing font in your doc. If your HTML doc doesn’t specify a font, the online browser picks one for you. Depending on how the browser is about up, this may very well be a serif font, just like the font utilized in my screenshot, or a sans-serif font. Serif fonts have a small stroke added to every letter, which makes these fonts a lot simpler to learn in print. Sans-serif fonts lack this additional stroke, which makes textual content seem sharper on a pc show. Common serif fonts embody Garamond or Times New Roman. Popular sans-serif fonts embody Roboto and Arial.
For instance, to set the doc physique font to Roboto, use this type:
physique { font-family: Roboto; }
By setting a font, you assume the individual viewing your doc additionally has that font put in. Some fonts have turn into so widespread they’re thought-about de facto “Web safe” fonts. These embody sans-serif fonts like Arial and serif fonts akin to Times New Roman. Roboto is a more moderen font and will not be accessible all over the place. So as an alternative of itemizing only one font, net designers normally put a number of “backup” fonts. You can add these various fonts by separating them with a comma. For instance, if the person does not have the Roboto font on their system, you’ll be able to as an alternative use Arial for the textual content physique by utilizing this type definition:
physique { font-family: Roboto, Arial; }
All net browsers outline a default serif and sans-serif font that you would be able to reference with these names. Users can change which font they like to make use of for serif and sans-serif, so aren’t more likely to be the identical for everybody, however utilizing serif or sans-serif in a font listing is normally a good suggestion. By including that font, at the very least the person will get some approximation of the way you need the HTML doc to seem:
physique { font-family: Roboto, Arial, sans-serif; }
If your font title is a couple of phrase, it’s important to put quotes round it. HTML permits you to use both single quotes or double quotes right here. Define just a few serif fonts for the heading and subheading, together with Times New Roman:
h1 { font-family: "Times New Roman", Garamond, serif; }
h2 { font-family: "Times New Roman", Garamond, serif; }
Note that the
h1, h2 { font-family: "Times New Roman", Garamond, serif; }
When writing documentation, many technical writers want to heart the principle title on the web page. You can use
h1 { text-align: heart; }
To assist daring and italics textual content to face out, put them in a barely completely different shade. For sure paperwork, I’d use darkish blue for daring textual content, and darkish inexperienced for italics textual content. These are fairly near black, however with simply sufficient delicate distinction that the colour grabs the reader’s consideration.
b { shade: darkblue; }
i { shade: darkgreen; }
Finally, I want so as to add additional spacing round my listing parts, to make these simpler to learn. If every listing merchandise was only some phrases, the additional house won’t matter. But the center merchandise in my instance textual content is kind of lengthy and wraps to a second line. The additional house helps the reader see every merchandise on this listing extra clearly. You can use the
li { margin-top: 10px; margin-bottom: 10px; }
This type defines a distance, which I’ve indicated right here as
Assuming you actually simply wish to add an additional clean line between the listing parts, you may as well use
li { margin-top: 1em; margin-bottom: 1em; }
The full listing of types in your HTML doc seems to be like this:
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
<style>
physique { font-family: Roboto, Arial, sans-serif; }
h1, h2 { font-family: "Times New Roman", Garamond, serif; }
h1 { text-align: heart; }
b { shade: darkblue; }
i { shade: darkgreen; }
li { margin-top: 1em; margin-bottom: 1em; }
</style>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The recreation will routinely "throw" the throwing sticks
for you, and show the leads to the lower-right nook
of the display screen.</p>
<p>If the "throw" is zero, then you definately lose your flip.</p>
<p>When it is your flip, the sport will routinely choose
your first piece on the board. You might or will not be
capable of make a transfer with this piece, so choose your piece
to maneuver, and hit <i>Space</i> (or <i>Enter</i>) to maneuver
it. You can choose utilizing a number of completely different strategies:</p>
<ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>proper</i> to
navigate to a selected sq..</li>
<li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left"
and "right" on the board. Note that this may routinely
comply with the "backwards S" form of the board.</li>
<li><em>Tab</em> to pick your subsequent piece on the
board.</li>
</ul>
<p>To give up the sport at any time, press <b>Q</b> (uppercase
Q) or hit <i>Esc</i>, and the sport will immediate if you would like
to forfeit the sport.</p>
<p>You win if you happen to transfer all your items off the board
earlier than your opponent. It takes a mixture of luck and
technique!</p>
</body>
</html>
When seen on an online browser, you see your Readme doc in a sans-serif font, with serif fonts for the heading and subheading. The web page title is centered. The daring and italics textual content use a barely completely different shade that calls the reader’s consideration with out being distracting. Finally, your listing gadgets have additional house round them, making every merchandise simpler to learn.
(Jim Hall, CC BY-SA 4.0)
This is a straightforward introduction to utilizing types in technical writing. Having mastered the fundamentals, you may be inquisitive about Mozilla’s HTML Guide. This consists of some nice newbie’s tutorials so you’ll be able to discover ways to create your personal net pages.
For extra data on how CSS styling works, I like to recommend Mozilla’s CSS Guide.
