Tutorial Formatting Guide

Submitted by admin (Contact Author) (Forums) on Wed, 2006-03-22 15:13. ::

Tutorial Formatting Guide

Version 1.2
Last edited 05/07/2008

If you want to publish a tutorial on HowtoForge, please read this guide to learn how to format your tutorial so that it fits into the look and feel of HowtoForge and looks attractive to as many readers as possible. These guidelines also help you to minimize the size of your document.

 

1 What Program Do I Use To Write My HowTo?

Use an HTML editor like Dreamweaver or any other HTML editor that creates valid HTML. Do not use MS Word to produce HTML content because Word produces "strange" HTML...

 

2 How Do I Start?

Ok, you're sitting in front of your HTML editor, ready to start, but what's next? Please copy this HTML skeleton to your editor:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<style type="text/css">
<!--
.command {
    padding: 1em;
    border: 1px dashed #2f6fab;
    color: black;
    background-color: #f9f9f9;
    line-height: 1.1em;
        font-family: Courier New, Courier, mono;
        font-size: 12px;
        font-style: italic;
}

.system {
    color: black;
        font-family: Courier New, Courier, mono;
        font-size: 12px;
        font-style: italic;
}

.highlight {
    color: #FF0000;
	font-family: Georgia, "Times New Roman", Times, serif;
	font-size: 12px;
	text-decoration: underline;
}
-->
</style>
</head>
<body>

</body>
</html>

Now you write your tutorial between the <body> and the </body> tags.

 

3 Formatting

3.1 Normal Text

Always use the default font for normal text and headings! Do not use <font> tags, and do not define your own CSS classes. All the formatting will be done by the HowtoForge CSS classes after you have published your tutorial on HowtoForge.

For example, something like

<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">This is a sentence.</font></p>

should be avoided. Simply use

<p>This is a sentence.</p>

instead. On HowtoForge, it will look like this:

This is a sentence.

 

3.2 Headings

Please use <h1>...</h1>, <h2>...</h2>, <h3>...</h3>, <h4>...</h4>, or <h5>...</h5> to format headings. Again, do not use <font> tags or CSS classes to format them.

The heading

<h3>This Is A Heading</h3>

will look like this on HowtoForge:

This Is A Heading

 

3.3 Commands

Please use the CSS class .command (defined in the <head>...</head> section in the HTML skeleton) to format shell commands so that the reader knows that it is something he has to execute on the shell. For example,

<p class="command">chmod 755 /path/to/file</p>

will look like this on HowtoForge:

chmod 755 /path/to/file

 

3.4 Contents Of Files

Contents of files should be enclosed with <pre>...</pre>. For example, if you want to show your readers the content of /etc/resolv.conf, you do it like this:

<pre>search server
nameserver 145.253.2.75
nameserver 193.174.32.18
nameserver 194.25.0.60</pre>

This will look like this on HowtoForge:

search server
nameserver 145.253.2.75
nameserver 193.174.32.18
nameserver 194.25.0.60

 

3.5 File Names, Protocol Names, System Specifications, Technical Specifications, Etc.

If you are writing about items related to the Linux system that are no commands, but that you want to be formatted in a special way nevertheless, you can use the CSS class .system. For example, if you mention a file name within normal text, it is a good idea to format it like this:

<p>Next we edit <span class="system">/etc/network/interfaces</span> so that it looks like this:...</p>

On HowtoForge, it will look like this:

Next we edit /etc/network/interfaces so that it looks like this:...

 

3.6 Highlighting

If you want to highlight something, you can use the CSS class .highlight. For example,

<p class="highlight">server1:</p>

looks like this:

server1:

 

4 Publish Your Tutorial

If your tutorial contains images, please skip this chapter and go to chapter five!

There are two content types you can use to publish your tutorial: story and book page. If you think your tutorial is short enough so that it fits on one page, select story. If your tutorial is rather long and you want to split it up into several pages, select book page.

 

4.1 Create A Story

After you have logged in on HowtoForge, please click on Contribute -> Create Content -> story:

Then you see the page with HowtoForge's WYSIWYG editor. Enter the story title and select one or more categories. If it's a very short tutorial, select one or more categories from the Mini-Howtos select box, otherwise one or more categories from the Howtos select box. (You can select more than one item by pressing [CTRL] while you select an item with your mouse pointer.)

In the Body WYSIWYG editor, switch to the HTML source code mode:

Then copy the HTML source code from your HTML editor (but only the part between the <body> and the </body> tags, not including them!) and paste it into the Body WYSIWYG editor, then click Update:

You can leave the Excerpt textarea (below the Body textarea) empty, the system will then auto-generate an excerpt for your tutorial.

Click on "Preview" or "Submit" afterwards, and you will see how your tutorial looks like on HowtoForge!

 

4.2 Create A Book

4.2.1 First Book Page

After you have logged in on HowtoForge, please click on Contribute -> Create Content -> book page:

Then you see the page with HowtoForge's WYSIWYG editor. Enter the story title and select one or more categories from the Howtos select box - don't touch the Mini-Howtos select box as a book cannot be regarded as a Mini-Howto. (You can select more than one item by pressing [CTRL] while you select an item with your mouse pointer.)

Under Parent select <top-level> as it's the first book page:

Then copy the HTML source code of your first book page from your HTML editor (but only the part between the <body> and the </body> tags, not including them!) and paste it into the Body WYSIWYG editor, then click Update, as shown in 4.1 Create A Story.

You can leave the Excerpt textarea (below the Body textarea) empty, the system will then auto-generate an excerpt for your tutorial.

Click on "Preview" or "Submit" afterwards, and you will see how your tutorial looks like on HowtoForge!

 

4.2.2 Further Book Pages

To add more pages to your first book page, click on Contribute -> Create Content -> book page.

Enter the same title as for the first book page plus - Page [no.] , e.g. - Page 2 for the second book page, - Page 3 for the third one and so on. Under Parent you select the first book page of your book so that page 2, page 3, page 4, etc. all have the same parent (the first page of the book).

Under Howtos and Mini-Howtos you select <none> twice:

The rest is the same as for the first book page.

 

5 Images

Please don't use images that exceed 550 pixels in width!

If your tutorial contains images, please zip your tutorial (HTML file created according to chapters 1 - 3) together with the images and email the zip file to ft@falkotimme.com. Please include your HowtoForge user name in the email so that we can publish the tutorial under your name.

 

6 Administrator Approval

Your new tutorial will not be available to the public immediately. One of our administrators will check it (formatting, contents, etc.), and most likely your tutorial will be approved. Afterwards it is available on HowtoForge.