Summary
This document provides a suggested process for editing HTML files. For purposes of this process, it is assumed that two people will be working together to edit and review.
Website posts and pages periodically need revisions. It’s good to make sure your site information is updated and current. A site scanner can report on broken links and accessibility concerns.
Usually a site owner will update their own site, particularly if the site is based on WordPress or a similar system that allows for easy editing. However, for HTML files, when editing and cleanup are needed, it is not uncommon for a site owner to enlist the help of someone familiar with HTML editing who has access to advanced software tools to make the process go more smoothly.
Site Owner and Editor/Assistant Roles
The site owner will be more familiar with the nuances of the writing style and unique spellings for names or technical terms. The site owner will have preferences regarding the use of bulleted lists, indents for quotes, and font styles to use. So, the site owner, or document author will work together with the assistant who will work with the HTML content directly to revise the document.
Editing Process
For the instructions below, the role of Site Owner will be abbreviated SO. The role of Editor / Assistant will be abbreviated as EA. Each numbered step has an initial description. Look for your role’s two-letter abbreviation to find the steps you are responsible for.
- PRIORITIZE CONTENT (SO). The Site Owner will identify high traffic or high importance content that should be worked on first.
- SITE SCAN (SA). The Editor Assistant will run a broken link check and provide the report to the site owner along with a Microsoft Word version of the page content. This can facilitate the review and editing process. The Word document is created by copying and pasting the web page content into an empty Word document.
- FIRST CONTENT REVIEW (SO). The site owner researches the broken links and provides suggestions for correction or removal with revised wording. These updates and suggestions are typed into the Word document in red text. Once complete, the site owner emails the assistant a copy of the Word document containing link correction suggestions. Other revisions might also be identified.
- COMPARISON (SA). Using the Microsoft Word – Compare Documents feature, the site assistant compares the original version of the document as it was in step #1 to the revised version of the document received after step #3. This produces a Word document that shows easily identifiable edits with markup revisions in a wide right column space, and also a gray vertical line next to any additions or changes. Be sure to enable the “Show Markup” option for this to work.
- GENERATE PDF (SA). The site assistant reviews the resulting document from step #4 and is more easily able to identify where corrections have been made. An ideal way to do this is to save the document as a PDF, and then with a tablet device, use a red digital pen to markup the document where changes are needed. An iPad and Apple Pencil could be used for this process.
- BACKUP OF HTML (SA). The site assistant should create a backup copy of the original HTML file with the date and time in the file name, such as yyyymmddhhmm or something similar to identify version of the HTML file. Also in the file name could be a few words describing anything significant about that version, such as “after fixing broken links” or “after font changes” could be added to the file name (without quotes).
- UPDATE OF HTML (SA). The site assistant updates the HTML page with the link corrections. This can be done using HTML editing software such as Coffee Cup or Microsoft Visual Studio Code. These are both free programs.
- GENERATE V4 WORD FILE (SA). The site assistant generates a Word file for what is now considered version four of the document. This is done by copying the web page content and pasting it into Word.
- REVIEW V4 WORD FILE (SO). The site owner reviews the content in Word, looking for grammar errors, and provides editorial requests in red text with brief summaries of what changes are needed in the text. These comments in red would be below paragraphs or text. The line number may be provided relative to the top or bottom of the paragraph, such as “in the third line from the top” or “in the second line from the bottom” of the above paragraph. Abbreviation can be used to reduce the amount of typing needed. Once completed, the site owner would send the revised document to the site assistant. The document at this point would be V5 for purposes of these instructions.
- CREATE WORKING LIST (SA). The site assistant will save version 5 of the Word file as a PDF and review it on a tablet computer using a digital pen, marking in red the suggested changes and enter arrows to clearly mark where the changes are to be made. This will help to discover where any questions arise regarding changes to be made. They will be easily and quickly identified visually in preparation for the next step.
- COMPLETE REQUESTS (SA). When all edits and changes are reviewed as described in the previous step, the site assistant will switch to using green digital ink on the tablet and make checkmarks next to each change when it’s completed. If time tracking is desired, the assistant can write the time of each change next to each change or at the top of each page. This makes it easy to see how much time was spent on the work being done. It would be possible to skip several steps and work directly from the Word document received in step #9 and #10. However, using the red pen and green pen system ensures that: (1) all changes have been seen with none overlooked, (2) all changes have been made. If this process is not used, a person looks back over a list of suggested changes with no record of what was completed, what work remains, where they left off working the last time, etc. It’s easier to keep detailed track of the work completed.
- EDITING THE HTML FILE (SA). The site assistant should be familiar with Visual Code Studio or a similar HTML editing system. Repetitive changes can be made more efficiently with search and replaced, but use caution with the feature since this can inadvertently introduce errors or changes throughout an entire document. Using search and replace in manual mode, rather than replace all, can be helpful. If a typo needs to be fixed, using the Find feature makes it quick and easy to find that text in the HTML. If an incorrect spelling or incorrect link needs to be corrected across multiple HTML pages of a website, the search and replace feature can (carefully) be used for that.
- SAVING ONGOING VERSIONS (SA). Every 30 to 60 minutes, the site assistant should save the current HTML file and make a copy of that file with the date and time in the file name. This ensures that work won’t be lost. These micro versions help if needing to go back to undo a correction. At some point.
- FINAL REVIEW PREP (SA). At this point, assuming all changes have been properly implemented, the site owner could make a final review of the page. For this purpose the site assistant could return to step #8 and generate a Word for the site owner to review.
- REPEAT. The site owner and site assistant can repeat steps 8 to 14 for as long as desired to refine the document being edited.
Other Page Improvements
In addition to simply fixing broken links and obvious typos, additional page improvements could be made. Suggestions are offered below.
Define Styles
Effective documents settle on a single font family and a few standard font sizes. Using styles in your HTML can consistently define how your text will appear. An example is below as shown in the header section of the page.
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Page Title Goes Here</title>
<style>
body {
background-color: white;
text-align: left;
color: black;
font-family: Arial, Helvetica, sans-serif;
margin: 30px;
}
p {
font-size: 1.2rem;
}
h1 {
font-size: 2.5rem;
}
h2 {
font-size: 2rem;
}
</style>
</head>
<body>
<p>Page content begins here...</p>This is a simple example to show the general syntax used for a style section that’s included in the page it modifies. It’s also possible to refer to a stylesheet file that contains site-wide styles. The above example is the most simple implementation that helps standardize styles for a single document.
Cleanup Excessive Font Styles
Some documents have numerous repetitive <font> style entries. If the above approach is used for the style standards in a document, then these individual font entries can be removed. Using headers such as <H2> rather than <big> is preferred. The HTML code <big> is no longer being used or recommended.
Avoid Underlines
Historically, in print, the underlining of text is to convey emphasis. In recent decades, in the age of the Internet, on web pages, underlining is typically reserved for hyperlinked words and text. Readers may try clicking on the underlined text thinking it’s a link. When their clicking does nothing they may assume it’s a broken link. So, it’s best to avoid underlining. If you must use underlining, do so sparingly.
Avoid Tables
In the past, tables in HTML would be used to position text and images next to each other, such as a photo to the right of a paragraph. Currently, the use of tables in this way can cause problems on smartphones and mobile devices. Instead, have the image above or below your paragraph.
Another reason to use a table would be to show rows and columns of numbers and text. However, this can also have display issues on mobile devices. It’s best to create a colorful using Microsoft Excel, or Word, or similar programs. Then save a copy of that table as a screenshot image. Then the table will visually be preserved in your document.
To make an HTML table show up properly, one needs to decide on the width or percentage of width to use, and then decide on the fonts, lines, and emphasis to use. It can be time consuming to create an attractive table in HTML.
Check for Character Set Issues
Sometimes a character set may be used that ultimately can’t be displayed. This could include some special characters that aren’t web compatible. In the example above, the HTML4 standard is used. The current standard for character set would be Unicode or UTF-8. If Unicode test is pasted into an HTML4 document set to an older character set, then the characters might not display properly. Switching to an older character set or using simpler characters could help. An example would be straight quotes (simple) versus curly smart quotes (not always compatible).
Create Optimized In-Document Navigation
Use anchor names in your document to easily navigate to key sections and back to the table of contents. This is done using the <a name=”anchorname”></a> command along with <a href=”#anchorname”>Link Name</a> to create the navigation system. You would replace anchorname with the name of the shortcut abbreviation you are linking to. Usually these would be at major chapters or sub-headings of your document.
Settle on Simple HTML and Formatting
Whenever possible, using simple HTML code can help. Here is a list of simple HTML codes to use. Using uppercase or lowercase doesn’t matter. Consistently using lowercase is more common and preferred. Simple codes begin with <something> and end with </something> where the something is the code that defines what is between the somethings. This will make more sense when you read the following.
- BLOCKQUOTE — When using a quote in your document, a brief quote can be placed inside of quote marks “like this.” A longer quote can be indented in your text. This makes it easier to read if your quote contains quotes. Then you won’t need single quotes, such as, “He told her, ‘Yes I will.'” To create an indented block quote use the command <blockquote> and </blockquote> at the beginning and end of the quote text.
- NOTE: Know that the use of a block quote might not carry through if the text is copied and pasted into Microsoft Word for example. The quote will no longer be indented and no longer look like a quote. So, other methods of identifying the text as a quote may work better depending on your long-term purpose and whether or not readers will be copying text from your document for research or other purposes. Also, if you copy and paste your HTML code into a WordPress website, the block quote may be rendered differently. The modernized rendering of an indented quote depends on your website theme. It may be displayed as an indented text with a bold blue line in the left column.
- BOLD — There are two options for making text bold. Having <b> and </b> will make the enclosed word bold. [Learn More] To convey importance, use <strong> and </strong> on either side of the word or phrase. [Learn More]
- CAPS — Putting words or headings in all caps is a nice way to make text stand out without using a full-size heading font. It is important to use CAPS and headings sparingly. There is not an HTML code for CAPS. Simply type using the caps lock key.
- CENTER – If you use the command <center> and </center> in your HTML before and after a title, for example, the word center in your HTML editor may appear in red. This is because it was used in HTML4 but is no longer supported in HTML5. The function may still work to display the text centered in browsers, but it’s not recommended for use. Instead, it is recommended that you use a style. [Learn More] If you define a style such as p.center in your styles section to have a certain font size, then you can use that style throughout your document with <p class=”right”> and </p> before and after the text to be centered. This is illustrated in the “Define Styles” earlier in this document.
- HEADINGS — Headings help to organize documents and help the reader get a quick visual overview. Well organized documents are easier to read. To make a word or line of text appear as a heading, use the <h2> and </h2> HTML codes before and after.
- ITALICS — Italics are a good way to convey emphasis. It is also common to write the titles of books, magazines, movies, and other complete works in italics. Use the <i> and </i> to make words italicized.
- NAVIGATION MENU — Content may be easiest to read and navigate if your web pages are at most a few pages long. Links to other pages by topic help the reader and also help search engines make sense of your content. However, if you end up with an HTML document that is the equivalent of 10 printed pages in length, or longer, you will likely want to have some navigation options added to the page. As explained above, using anchors for internal document navigation can be helpful.
- ORDERED LIST — An ordered list is also known as a numbered list. These lists are displayed as a group of entries. The group has a blank line above and below the group, but each entry is single spaced with no space between entries. It is a clean and efficient way to display any content that displays well as a list. The list group will begin with <ol> and then each entry in the list will have <li> and </li> before and after it. At the end of the list, the </ol> code will be used.
- PARAGRAPH — It is important to define paragraphs in your HTML to distinguish between separate blocks of text. Browsers will typically show separate paragraphs with a space above and below. To designate a section of text as a paragraph, use the <p> and </p> before and after the text in your HTML.
- UNORDERED LIST — An unordered list is also known as a bullet list. These lists are displayed as a group of entries. The group has a blank line above and below the group, but each entry is single spaced with no space between entries. It is a clean and efficient way to display any content that displays well as a list. The list group will begin with <ul> and then each entry in the list will have <li> and </li> before and after it. At the end of the list, the </ul> code will be used.
