Introduction

General Overview

Welcome to the Software Training for Students Manual Editing Guide! This resource will provide you with all of the information needed to create, revise, edit, and update the training manuals used by STS. It should be pretty comprehensive already, but if there is information that is not currently included but that you think would be helpful to add, make your suggested addition known via the manual update submission form. This will add it to the queue so it can be updated in the future by an STS trainer - maybe even you!

HTML and CSS

All current STS Manuals are written in standard HTML5 along with a few custom CSS classes for formatting certain elements (instruction lists, screenshots, etc.). The code we use is pretty straightforward, so if you've worked with raw HTML at all in the past, you shouldn't have much trouble picking up a manual's source files and making updates right away.

If you've never worked with HTML before, this would be a great opportunity to check out the STS manual for Web Design 1: HTML and learn the basics.

The CSS classes used for formatting are also pretty straightforward, so if you have a basic understanding of how to add a class to an HTML element via the class = "classname" attribute, you shouldn't have any trouble using the CSS reference section at the end of this document to format your manuals.

What Should I Use To Edit?

There are a bunch of code editor programs out there that make working with HTML, CSS, JavaScript, and most other programming languages much easier than coding with a plain text editor like Notepad or TextEdit. But which one is the right code editor to use?

The correct answer (and also the one that is the least helpful for someone new to coding) is, whichever one works for you. Most can do similar things (like automatic code completion/HTML tag generation, etc.), but each one has a slightly different feel and offers different workflows.

Some of the most commonly used code editors include:

• SublimeText
• Visual Studio Code
• Brackets
• Atom
• Notepad++

All of these do the job of making your code-editing life easier, but for the purposes of this guide, we will look at setting up Brackets from Adobe.

Some of the features that make Brackets helpful for our purpose:

• It is free, open-source, and cross-platform: Mac, PC, and Linux versions are available and have equal features.
• HTML tag auto-complete
• Live Preview, so you can see your changes without having to manually refresh your web browser
• Large selection of plugins/extensions to make common tasks like wrapping text in tags and correctly indenting nested HTML much easier
• A wide variety of themes to customize your editor's appearance

But what about [other editor]?

If you have another editor that you prefer, you may be saying "But [my editor of choice] can do all of that, and more! Clearly [my editor of choice] is better!" And for your needs that may be true! We've found that for people who may not be as experienced working with a coding environment, Brackets offers a good balance between customizability and user-friendliness, which is why it is being recommended here. If you have suggestions or recommendations for another editor, feel free to add a section explaining how to set it up for our purposes.

Setting Up Your Editor

The default installation Brackets is already a very powerful and full-featured editor, but a few simple tweaks can make it even better for the task of editing STS manuals.

If you have another code editor that you prefer and it also supports plugins/extensions, these steps may also apply.

If you haven't already, you can download and install the Brackets app from their website here.

Helpful Brackets Features

There are a number of built-in features that make life easier when working with Brackets.

Live Preview

One feature that makes Brackets particularly helpful when doing this kind of HTML editing is the Live Preview tool.

To launch Live Preview, hit the lightning icon in the upper right of the editor window

When active, the Live Preview function will show you a real-time preview of your working document, that updates every time you save.

Depending on your setup, Live Preview may highlight in realtime of whatever HTML your cursor is currently within.

Open Folder...

Opening File > Open Folder... lets you set a current working folder in the file browser on the left side of the screen.

Setting this to your manuals folder gives you easy access to the subfolders that contain your manual project files.

Shortcuts

Some useful Brackets shortcuts/features:

• Duplicate current line: Cmd+D (Mac) or Ctrl+D (Windows)
• Delete current line: Cmd+Shift+D (Mac) or Ctrl+Shift+D (Windows)
• Collapse Current Element: Cmd+Alt/Option+[(Mac) or Ctrl+Alt+[(Windows)
• Expand Current Element: Cmd+Alt/Option+] (Mac) or Ctrl+Alt+] (Windows)
• Open Two Files at once: File > Horizontal Split or File>Vertical Split

Extensions and Themes

Extensions

Finding and installing additional plugins for Brackets is simple. Simply click the icon in the upper right that looks like a Lego block:

Extensions we suggest you install right away:

• Emmet (Developer: Sergey Chikuyonok)
• Indentator (Developer: Andrew Huth)
• Brackets Tools (Developer: Yasin Kuyu)

Emmet

Emmet is a favorite in the web-development world for its ability to generate longer strings of HTML from a few keystrokes.

Tag expansion

When using Emmet in Brackets, if you type text and hit the Tab key, it converts the last bit of text into opening and closing HTML tags.

For example:

becomes

Additionally, if you add any class selectors, those get automatically populated when you hit Tab as well.

For example, section.topic becomes <section class="topic"></section> when you hit the Tab key.

This works with multiple classes as well - you just need to chain them one after the other with dots before each class.

For example, span.type-text.highlight expands to <span class="type-text highlight"></span> when you hit Tab.

Wrapping Text

Another helpful feature of Emmet is the ability to wrap existing text in tags via a shortcut.

Highlight the text around which you'd like to wrap tags and hit
Cmd + Shift + A (Mac) or Ctrl + Shift + A on Windows. Enter the text to wrap around the selection, and hit Enter/Return.

Cmd + Shift + A (Mac) or Ctrl + Shift + A (Windows) brings up the text entry field where you can enter the tags you'd like to apply.

Enter the text to wrap around the selection, hit Cmd + Shift + A (Mac) or Ctrl + Shift + A (Windows), then hit Enter/Return to apply your tags.

Indentator

One of the features that makes HTML such a useful language is its ability to nest content within other content. Being able to see at a glance the structure of what content is nested where makes life much easier, both for knowing the overall arrangement of the elements of your web page and also for troubleshooting if you may have an extra tag somewhere that is throwing things off.

Having a tool to automatically indent items with a single keystroke or command makes this process much simpler (and nicer to look at), which is where Indentator comes into play.

To automagically indent your HTML file (or your CSS, or your JavaScript, or any code with standard syntax), simply hit the shortcut keys:

Ctrl + Option + I (Mac) or Ctrl + Alt + I (Windows).
Note that it is the actual Ctrl key on a Mac and not the Cmd key for this shortcut.

This will automatically indent the entire file that is currently open.

Brackets Tools

The Brackets Tools plugin is an assortment of different tools that make working with text easier.

Encode HTML

One tool that is particularly helpful when working with HTML is the ability to convert code from HTML into characters that can be displayed in a web browser without rendering it as actual HTML.

For example:

To make <section class="topic"></section> appear in HTML without actually rendering the Section element, it needs to be written using special codes that tell the browser to display the HTML characters rather than convert them to HTML elements.

That would need to be written as: &lt;section class="topic"&gt;&lt;/section&gt;

Typing those codes out by hand can be an extremely tedious and error-prone process. Using the Brackets Tools extension makes this simple. All you need to do is highlight the text, then go to Tools > HTML Encode (or right-click and select HTML Encode)

Use caution: if you do not have a selection made and you use the HTML Encode feature, it will convert your entire document and eat all HTML code contained within it.

There are many more things that the Brackets Tools extension makes easier - check out the documentation at the developer's GitHub page.

Themes

Brackets also has a number of options for customizing the color scheme of your editor. These are packages called themes and are available by clicking that same Extensions icon in the upper right.

To install a theme, simply click the Install button.

Once installed, you can select your themes from the View > Themes... menu.

The screenshots in this manual feature Brackets with the Cobalt theme enabled, which is available from the Themes directory.

Manual Structure

Here are some items that will be helpful for you to know as you get started editing STS manuals.

Folder Structure

It is highly recommended that you create on your computer a specific folder that will be dedicated to editing STS manuals. This will make it easier to keep manual files organized and know what is where.

The screenshot below uses a folder called manuals as the top-level folder in which the other manual files live:

All other folders should be on the same level in the file hierarchy relative to each other. It doesn't matter where they are, as long as they are all on the same level as the master-files folder, which we'll discuss in a moment.

Manual Folders

All manual project folders will have the same structure:

• An index.html file that contains the manual content
• An images folder, where all screenshots and helper images live.

That's all you need! Everything else lives in the master-files folder, and is linked in the <head> tag of each manual's index.html file.

Master Files

All of the STS manuals reference the same set of CSS and JavaScript files, which live in the master-files folder. The links to the CSS and JavaScript in each manual's HTML use a relative file path, which means that they will look for the master-files folder exactly one level up from where the manual's .HTML file is located. This is helpful if we ever need to change the location where our manual files are hosted, because we can easily move the entire manuals folder to another location or even another server without needing to update the links for each of our 40+ manuals.

This also means that in order for your local project to have the style and functionality of the actual manuals, you'll need to have a local copy of the master-files folder for in your main manuals folder.

To get the latest version of the manual files, simply download the .zip file at https://sts.doit.wisc.edu/manuals/master-files/master-files.zip and unzip it in your manuals folder. Any STS manual folders located on the same level as this folder should automatically pull in the master files.

Blank Manual Template

To get started on a new manual from a blank template, simply download and unzip the blank-manual-template.zip folder to your local manual editing environment.

This project will have the correct <head> tag and an image folder built already, so you can start right in on writing your manual.

If you would rather build a manual project folder from scratch, you can consult the sections below.

Master files (CSS and Javascript): master-files.zip

Blank manual template: blank-manual-template.zip

The <head> Tag

All of the project manuals should have (nearly) identical <head> tags:

            
<head>
    <title>STS Manual Editing Guide</title>
    <meta charset="utf-8">
    <meta name="description" content="Software manual provided by Software Training for Students at the University of Wisconsin.">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' id='uwmadison-fonts-css' href='https://brand.wisc.edu/content/themes/uw-theme/dist/fonts/uw160/fonts.css?ver=1.1.1' type='text/css' media='all' />
    <link rel="stylesheet" type="text/css" href="../master-files/css/stylesheet.css">
    <script src="../master-files/highlight.js"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
    <script src="../master-files/smooth-scroll.js"></script>
    <script src="../master-files/primary-functions.js"></script>
    <script src="../master-files/ga.js"></script>
</head>

           
            

The only thing that you might ever need to change in the <head> tag is the content of the <title> element, which should match the name of the manual.

If for some reason the <head> tag is broken or has otherwise been changed from what you see in the example above, you can copy and paste the contents of the head.html file from the master-files folder to replace it.

Front Page

The top of the manual includes a <div> tag with the ID of manual-front-page:

<div class="manual-front-page"> 
    <div id="coverpage-title"> 
        <h1>STS Manual Editing</h1> 
        <h2>How-to and style guide</h2> 
    </div> 
    <div id="about-page"></div> 
    <div id="outline"></div> 
</div>                
            

The <div> tags with the IDs about-page and outline tags are empty by design: they automatically get populated with their respective content by the manual's JavaScript.

Some existing HTML manual files may have some additional text or image files in these tags. If you encounter such a manual, delete the extra tags and replace them with what you see above.

Outline/Topic Sections

The Topics outline gets automatically populated by the manual's respective sections, as long as the sections are set up with the following structure:

<section class="topic"> 
    <h1>Topic title</h1>
    Topic content
</section> 
            

Each section/topic should only have one <h1> tag, and it should live at the very top of the section.

Images

All screenshots, GIFs, and other helper images for each manual should live in the images folder within each manual's project folder.

This keeps all images in one location for easy access. It also allows you to embed images via the <img> tag using a relative link:

<img src="images/01-Folders.png" alt="Screenshot of a project folder">

Alt Text

Every image element has an alternate text element alt="" that needs to be filled with a description of the content of the image. This is important both because it provides accessibility for individuals who use assistive technology like screen readers and also because it helps search engines accurately catalog and index manual materials.

Images without alt text will appear with a red line around them, as a visual reminder that they need alt text added.

Reference Boxes

Any time you explain a tool or technique that is helpful for a learner to know about in a general sense - for example, introducing the Quick Selection Tool in Photoshop, or explaining what a tag is in HTML - you should create a Reference box.

These boxes get automatically collected and populated at the end of each manual in a section called Reference.

                    
<div class="tool-reference">
    <h3>Tool Title</h3>
    <img src="images/optional-image.jpg" alt="Optional image">
    <p>Tool Description</p>
</div>
                    
                

Here is an example of what a Reference box for the Live Preview tool would look like:

Live Preview

The Live Preview button lets you see a real-time preview of the file you are editing, as it will display in the browser.

Live Preview can highlight the part of the file that you are currently editing, as well as help you navigate within the editor by clicking different parts of the file.

These can also be helpful with code blocks rather than images:

                    
<tag>Content</tag>    
                    
                

Text

Adding text to your manuals is one of the most common things you will do as a manual editor. Here are a few things to keep in mind that will make your editing less frustrating.

<p> Tags

Any text in the training manual that is not inside another element (for example an instruction list or section heading) needs to be within paragraph tags, or <p></p> tags.

<p>All text needs to go inside paragraph tags</p>

The only elements (other than text) that can go inside paragraph tags (without potentially breaking the HTML formatting) are the following:

• Links, aka anchor tags: <a></a>
• Images: <img>
• Span text (helpful for highlighting): <span></span>
• Strong, aka bold: <strong></strong>
• Emphasis, aka italics: <em></em>
• Keyboard shortcuts: <kbd></kbd>

Bold and Italics

To make text bold, wrap the text in <strong></strong> tags:

<strong>Bold text</strong>

To make text italicized, wrap the text in <em></em> tags:

<em>Italicized text</em>

Highlighting

To add highlighting to text, use the following CSS classes:

Reminder: adding a CSS class to an element is as simple as adding class="classname" inside the opening tag:

<span class="highlight-type">Example</span>

Most of the time you will probably use these within <span> tags.

Keyboard shortcuts

Use the kbd element when giving keyboard shortcuts.

Example:

Ctrl/Command + C

<kbd>Ctrl/Command</kbd> + <kbd>C</kbd>
                

Lists

There will often be situations in which you will need to create lists of items, and the manuals have some conventions build to handle these.

Ordered and Unordered Lists

When using a regular ordered list (<ol></ol>) or unordered list (<ul></ul>), the results will appear as follows:

Ordered list:

1. Ordered list item 1
2. Ordered list item 2
3. Ordered list item 3

Unordered list:

• Unordered list item 1
• Unordered list item 2
• Unordered list item 3

Instruction Lists

When creating lists of instruction steps, add the class instruction-list to the instruction list, and its steps will generate the green counter numeral automatically.

If you nest one instruction list within the list item for an existing instruction list, it will create a new set of numbers, in a different color.

1. Instruction step 1
2. Instruction step 2
   1. Instructions within an instruction step, A
   2. Instructions within an instruction step, B
3. Instruction step 3

Links

Just like in standard HTML, adding a link is as simple as adding an anchor tag, with the link destination in the href attribute, and the link text (aka what you click on) between the opening and closing tags.

<a href="https://www.linkgoeshere.com">The Text To Click On</a>

Becomes:

The Text To Click On

Code blocks

When working in a coding language like HTML, JavaScript or Python, it is often helpful to present that code differently from regular text, with features like syntax-highlighting.

To use code highlighting, you use two tags: <pre></pre> and then a <code></code> tag within that one. For example:

<pre>
<code>
    if(code = true) { 
        code++ ;
    }
</code>
</pre>

    

Will produce the following:

        if(code = true) { 
            code++ ;
        }
    

One thing to note is that when using code blocks, white space matters. This means that the number of spaces in from the start of the line of text will be accurately rendered on screen (rather than being removed, as happens with HTML most of the time).

Images

As the saying goes, a picture is worth a thousand words. Being able to see things visually in addition to having a description can mean the difference between confusion and understanding, especially when putting together a resource that teaches other people new skills.

Having real-world screenshots of what's being explained is an important aspect of assembling a helpful training manual, and there are a few tips and guidelines that will help make your screenshots effective and also make life as a manual-editing-person easier to manage.

Capturing Screenshots

Depending on your operating system, there are different ways to capture screenshots.

MacOS

If you are using a Mac, there are built-in keyboard shortcuts to capture static screenshots.

• Cmd + Shift + 3 captures a full-screen image of everything on your screen (including additional monitors, if you are using multiple displays)
• Cmd + Shift + 4 allows you to specify part of the screen to capture.

Both of these options save a file to the desktop with the date and time, titled for example Screen Shot 2018-05-23 at 12.13.10 PM.png, which you can then rename and move to the images folder of your manual's project folder.

Windows

If you are using Windows, you can use the default Snipping Tool app to take a screenshot of all or part of the screen.

Simply click the New button and record the section of screen you'd like to make into a screenshot, then hit the Save button to save it to your manual's images folder.

Focus on What's Relevant

Try to focus screenshots on the specific thing that is being described. For example, if you are trying to show off a specific item in the Photoshop options bar, avoid having a full-size screenshot showing the entire entire screen.

For example, a screenshot like this may be helpful for seeing the details of the options menu:

A larger screenshot may not be as helpful:

In some situations, it may be useful to have a larger screenshot, for example if you are pointing out the context/location of a given item.

In these cases, adding highlighting to the item you are pointing out will be helpful:

On Macs, these highlight boxes, arrows, etc. can be added via the Preview app, by using the Tools > Annotate menu.

On Windows, the Paint app comes pre-installed and is a great option for adding rectangles, arrows, etc., but there are also many free annotation tools available from third-party developers.

Screenshots That Move: GIFs

There may be situations where seeing things in motion may be helpful for explaining a tool or concept. For these cases, an animated GIF is a great choice.

In the past, our manuals were PDF files, meaning static screenshots were the best we were able to offer. Having moved to live HTML pages for documents means we can now use GIFs, which is exciting!

MacOS

To capture GIFs on a Mac, you can use the free GIPHY Capture app.

Windows

For Windows, the ScreenToGif app is a great option.

Both programs have built-in editors and export options that let you target only the most relevant parts of your motion capture.

Because GIFs can be relatively large files and don't need particularly fast frame rates, save your GIF captures at low frame rates: 10 to 15 frames per second (FPS).

Screenshot Management

Because manuals may end up having many, many screenshots, it is important to name the image files in the images folder descriptively. You may also want to add numbers to the start of the filenames that roughly correlate to their order in the manual.

Some helpful tips when saving screenshots and GIFs:

• Avoid spaces and other special characters (e.g. commas, periods, asterisks, & and %, etc) in filenames. These can cause file-linking errors and prevent images from appearing.
• Acceptable characters are A-Z, 0-9, and dash (-) or underscore ( _ ) in place of spaces.
• Numbering images with the rough order in which they appear in the manual can be helpful for knowing which image goes where.
  
  It's not required to go back and re-number all screenshots if you're editing an existing manual, but if you are starting a new manual from scratch, this convention can make life much easier.
• When editing in Brackets, typing img and hitting Tab will auto-expand the HTML and place your cursor between the quotes in the src="" tag. From here, typing images/ will give you a mini file-browser that makes it easier to select the files in that folder.

Figures and Captions

To create an image with a caption, you must use a <figure> tag.

The structure for this tag looks like this:

<figure>
    <img src="images/screenshot.png" alt="A Screenshot with Caption">
    <figcaption>Caption for your image</figcaption>            
</figure>
        

and will produce something that looks like this:

CSS Classes for Styling

There are a number of CSS classes that can be used to adjust how elements appear on screen.

These can be added to most elements that you are likely to be working with:

• <p>
• <div>
• <img>
• <a>

Remember that to add a class to an element, simply add class="classname" within the opening HTML tag. If you would like to add more than one class, add spaces between each class name.

For example, if you wanted to add the center and type classes to a paragraph tag, it would look like this:

            <p class="center type">Paragraph contents go here</p>
            

Positioning

The following classes will affect how an element is positioned.

left

Makes elements appear on the left and NOT have text flow around it.

Example:

This paragraph text is not flowing around the image with class left.

float-left

Makes elements float on the left AND wraps text around it.

This may make things look a bit weird if you have smaller images/elements.

Example:

This text is flowing around the image with class float-left.

half-left

Makes elements take up the left half of the screen and NOT flow text around them.

Example:

This paragraph text is NOT flowing around the image with tag half-left

right

Makes elements appear on the right and NOT have text flow around it.

Example:

This paragraph text is not flowing around the image with class right.

float-right

Makes elements float on the right AND wraps text around it.

This may make things look a bit weird if you have smaller images/elements and may require you to wrap the element in a <div class="full-width"></div> tag to prevent things getting flowed in unexpected ways.

Example:

This text is flowing around the image with class float-right. It is also surrounded by a <div class="full-width"></div> tag

half-right

Makes elements take up the right half of the screen and NOT flow text around them.

Example:

This paragraph text is NOT flowing around the image with tag half-right

Sizing

large

Adding the large tag to an element forces it to 100% the width of whatever element it is currently within.

Example:

medium

Adding the medium tag to an element forces it to 50% the width of whatever element it is currently within.

Example:

small

Adding the small tag to an element forces it to 25% the width of whatever element it is currently within.

Example:

Informational Boxes

The following classes create boxes attention-grabbing boxes that prominently feature the content within.

These can be applied to paragraph, span, or div elements. If you have multiple items that will go in the box, for example an image as well as paragraph text, it's recommended to wrap all elements that should appear in the informational box within a surrounding div tag with the class on it.

For example:

<div class="shortcut">
    <p>Text goes here.</p>
    <img src="images/01-Folders.png" alt="Image in a shortcut informational box">
</div>                    
                

becomes

Text goes here.

These can also be used with the positioning classes.

For example:

<div class="shortcut right">
    <p>Text goes here.</p>
    <img src="images/01-Folders.png" alt="Image in a shortcut informational box">
</div>                    
                

becomes

Text goes here.

sidebar-note

This class makes an element appear on the right side of the screen, with smaller text.

It is helpful for supplemental information or factoids that may be interesting for a learner but that are not directly related to the class materials.

You can also use the HTML element <aside></aside> for the same effect.

<div class="sidebar-note">
    <p>This sidebar is over on the right because it is not essential,
    but may offer interesting insights.</p>
    <img src="images/01-Folders.png" alt="Example image in sidebar.">
</div>
<p class="sidebar-note">A single element rather than a div.</p>
<aside>This is an aside.</aside>
    
               

becomes:

This sidebar is over on the right because it is not essential, but may offer interesting insights.

A single element rather than a div.

Styling

There are a few classes used to add particular style features to elements.

border

This class adds a border around an image or text element.

Examples:

This paragraph has a border around it.

shadow

This class adds a subtle drop-shadow around an image or text element.

It can be helpful for adding the appearance of depth or visual differentiation to an image with a light-colored background

Examples:

This paragraph tag has a shadow around it.

rounded

This class rounds the corners of whatever element it is attached to.

Example:

CSS reference

These are all classes that you may need to use in the course of writing or editing STS manuals.

General

Informational Boxes

Positioning

Sizing

Text and alignment

Styling