Documentation is a crucial a part of any technical mission. Good documentation tells the top person find out how to run this system, find out how to use it, or find out how to compile it. For many tasks, plain textual content documentation is the usual. After all, each system can show plain textual content information.
However, plain textual content is limiting. Plain textual content information lack formatting components like italics textual content, daring textual content, and titles. To add these components, we are able to leverage HTML. HyperText Markup Language (HTML) is the markup language utilized in all internet browsers. And with a bit additional effort, you should use HTML to jot down mission documentation that may be learn by everybody.
HTML makes use of a sequence of tags enclosed in angle brackets to manage how totally different components of a doc must be displayed. These tags outline components in an HTML doc, akin to doc headings, paragraphs, italics textual content, daring textual content, and other forms of textual content. Almost each tag is available in a pair: an opening tag, like <p> to begin a paragraph, and a closing tag to finish the ingredient, akin to </p> to finish a paragraph. When utilizing these tags, keep in mind this rule: should you open a tag, it’s essential shut it. Not closing a tag correctly can lead to the online browser incorrectly.
Some tags outline a block inside the HTML doc, whereas others are inline. For extra details about block and inline components, learn my different article about a gentle introduction to HTML.
Start an empty doc
Begin by making a boilerplate empty HTML doc. Every HTML doc ought to present a doc kind declaration. Use the one tag <!DOCTYPE html> on the primary line of the HTML file to outline an HTML doc. The HTML customary additionally requires that pages wrap the doc textual content in two block components: <html> to outline the HTML doc, and <physique> to outline the physique textual content. While HTML would not require indenting every new code block, however I add it anyway so you possibly can see that <physique> is definitely “inside” the <html> block:
HTML paperwork additionally want a <head> block earlier than the <physique> that gives additional info known as metadata concerning the web page. The solely required metadata is the title of the doc, outlined by the <title> ingredient. An empty doc may seem like this:
Add the textual content
Let’s train some HTML data by adapting an current plain textual content “Readme” file to HTML. For this instance, I’m utilizing a part of the documentation about find out how to play an open supply board sport, known as Simple Senet:
HOW TO PLAY SIMPLE SENETThe sport will mechanically "throw" the throwing sticks for you, and
show the ends in the lower-right nook of the display screen.If the "throw" is zero, you then lose your flip.
When it is your flip, the sport will mechanically choose your first
piece on the board. You might or might not be capable of make a transfer with
this piece, so choose your piece to maneuver, and hit Space (or Enter) to
transfer it. You can choose utilizing a number of totally different strategies:- Up/down/left/proper to navigate to a particular sq..
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this can mechanically comply with the "backwards S"
form of the board.- Tab to pick out your subsequent piece on the board.
To stop the sport at any time, press Q (uppercase Q) or hit Esc, and
the sport will immediate if you wish to forfeit the sport.You win should you transfer your whole items off the board earlier than your
opponent. It takes a mix of luck and technique!
Start by including this Readme textual content into your empty HTML file. The principal content material of an HTML web page is the <physique>, in order that’s the place you set the textual content:
<!DOCTYPE html>
<html>
<head>
<title>Title of the doc</title>
</head>
<body>
HOW TO PLAY SIMPLE SENET
The sport will mechanically "throw" the throwing sticks for you, and
show the ends in the lower-right nook of the display screen.
If the "throw" is zero, you then lose your flip.
When it is your flip, the sport will mechanically choose your first
piece on the board. You might or might not be capable of make a transfer with
this piece, so choose your piece to maneuver, and hit Space (or Enter) to
transfer it. You can choose utilizing a number of totally different strategies:
- Up/down/left/proper to navigate to a particular sq..
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this can mechanically comply with the "backwards S"
form of the board.
- Tab to pick out your subsequent piece on the board.
To stop the sport at any time, press Q (uppercase Q) or hit Esc, and
the sport will immediate if you wish to forfeit the sport.
You win should you transfer your whole items off the board earlier than your
opponent. It takes a mix of luck and technique!
</body>
</html>
Without additional modifications, this HTML doc seems to be fully fallacious once you view it in an internet browser. That’s as a result of HTML, like most markup techniques, collects phrases from the enter file and fills paragraphs within the output. Because you haven’t but added different markup, an internet browser shows the textual content in a single paragraph:
(Jim Hall, CC BY-SA 4.0)
Body paragraphs
Your first step in updating this Readme file to HTML is to mark each paragraph so the online browser can show it correctly. The tag to outline a paragraph is <p>. While not every little thing on this file is definitely a paragraph, begin by wrapping every little thing in <p> and </p> tags:
<!DOCTYPE html>
<html>
<head>
<title>Title of the doc</title>
</head>
<body>
<p>HOW TO PLAY SIMPLE SENET</p>
<p>The sport will mechanically "throw" the throwing sticks for you, and
show the ends in the lower-right nook of the display screen.</p>
<p>If the "throw" is zero, you then lose your flip.</p>
<p>When it is your flip, the sport will mechanically choose your first
piece on the board. You might or might not be capable of make a transfer with
this piece, so choose your piece to maneuver, and hit Space (or Enter) to
transfer it. You can choose utilizing a number of totally different strategies:</p>
<p>- Up/down/left/proper to navigate to a particular sq..</p>
<p>- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this can mechanically comply with the "backwards S"
form of the board.</p>
<p>- Tab to pick out your subsequent piece on the board.</p>
<p>To stop the sport at any time, press Q (uppercase Q) or hit Esc, and
the sport will immediate if you wish to forfeit the sport.</p>
<p>You win should you transfer your whole items off the board earlier than your
opponent. It takes a mix of luck and technique!</p>
</body>
</html>
This makes the Readme look extra like a doc you need to learn. When you view the brand new doc in an internet browser, each paragraph begins on a brand new line, with some additional area above and under. The paragraph is the commonest instance of a block ingredient.
(Jim Hall, CC BY-SA 4.0)
Headings and subheadings
The first line in your content material is your doc’s title, so it is best to make this right into a heading. HTML supplies six ranges of headings, from <h1> to <h6>. In most paperwork, you may use <h1> to outline the title of the doc, and <h2> for main subsections. Make this modification in your pattern Readme doc. Use the identify of this system (“Simple Senet”) as the principle part title, and “How to Play” as a subsection within the doc.
Note that on this instance, I’ve additionally up to date the <title> within the doc metadata to make use of the identical title because the <h1> heading. This would not really change how browsers show the doc, however it’s a good apply to make use of:
By including these part headings, you’ve got made the doc simpler to learn:
(Jim Hall, CC BY-SA 4.0)
Ordered and unordered lists
Your doc features a record of various methods to navigate the board sport. Because this doc began out as a plain textual content file, every merchandise within the record begins with a hyphen. But you should use HTML to outline these three paragraphs as record gadgets.
HTML helps two sorts of lists: ordered and unordered lists. An ordered record <ol> is a numbered sequence, which you may use to outline a sequence of steps. An unordered record <ul> defines an inventory of things which will or is probably not associated, however are typically not completed so as. Both lists use record gadgets <li> for entries inside the record.
Update the Readme doc to make use of an ordered record as an alternative of paragraphs. This presents the three navigation choices in a numbered record:
This presents the three choices in a numbered record:
(Jim Hall, CC BY-SA 4.0)
However, these three gadgets aren’t actually a sequence of steps, however totally different choices to maneuver the choice within the Simple Senet sport. So as an alternative of an ordered record, we need to use an unordered record. This requires updating the <ol> to <ul> within the doc:
The unordered record makes use of bullets for every record merchandise, as a result of the entries will not be a part of a sequence:
(Jim Hall, CC BY-SA 4.0)
Bold and italics
You can spotlight sure info within the doc by making use of daring and italics types. These are quite common textual content types in technical writing. You may use daring to focus on vital info, or italics to emphasise key phrases and new phrases.
The daring tag was initially outlined as <b>, however newer variations of the HTML customary want the <sturdy> tag to point sturdy significance, akin to key steps in a set of directions. Both tags are legitimate, however are semantically barely totally different. <b> now means “bring attention to.”
Similarly, the unique HTML customary used <i> for italics textual content. Later variations of HTML as an alternative want <em> to carry emphasis to components of the textual content. Instead, <i> now identifies idiomatic textual content or technical phrases.
For this instance, use daring to determine the single-letter keypresses, and italics to point particular keys on a keyboard like Enter and Space. For simplicity, use <b> and <i> tags right here (however you may use <sturdy> and <em> tags as an alternative to get the identical impact:)
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The sport will mechanically "throw" the throwing sticks for you, and
show the ends in the lower-right nook of the display screen.</p>
<p>If the "throw" is zero, you then lose your flip.</p>
<p>When it is your flip, the sport will mechanically choose your first
piece on the board. You might or might 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
transfer it. You can choose utilizing a number of totally different strategies:</p><ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>proper</i> to navigate to a particular sq..</li><li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left" and "right" on the
board. Note that this can mechanically comply with the "backwards S"
form of the board.</li>
<li><em>Tab</em> to pick out your subsequent piece on the board.</li>
</ul><p>To stop the sport at any time, press <b>Q</b> (uppercase Q) or hit <i>Esc</i>, and
the sport will immediate if you wish to forfeit the sport.</p>
<p>You win should you transfer your whole items off the board earlier than your
opponent. It takes a mix of luck and technique!</p>
</body>
</html>
These additional types assist particular gadgets to face out within the textual content:
(Jim Hall, CC BY-SA 4.0)
The level of writing documentation is for customers to know find out how to use the software program, so each open supply mission ought to take the time to jot down documentation in a means that’s simple to learn. With a couple of primary HTML tags, you possibly can write documentation that presents the data extra clearly to your customers.
For extra info on utilizing HTML to jot down documentation, try the entire HyperText Markup Language reference at MDN, the Mozilla Developer Network, hosted by the Mozilla internet mission.
