Best Practices for Building Web Pages

Getting Content into the CMS

Sometimes, just shifting content from where it is written and approved to the CMS “content” window is the most fraught step. A simple cut-and-paste operation (cmd-x, cmd-z) between windows imports both the text and always-problematic hidden formatting (or “markup”). The effects of this markup may not be immediately obvious to the eye, but it is visible to search engines and browsers. It can corrupt the way a page renders or cause it to not render at all in some browsers. To avoid these issues, use these tips:

• Always import text using "paste as plain text" or by pasting directly into the HTML window, then apply the correct element markup (e.g., H2 for first-level headings; paragraph for regular text). Use the “paste as plain text” button or simply open the HTML view “<>” of your copy and paste text there. (The HTML view will strip out all the formatting, too.)
• Don’t compose in the CMS. CMSes are not built for composition but for posting. The text editor tends to insert markup that breaks your page: empty spans, non-breaking spaces, font changes, and other formatting are typical. The more you edit in this window, the more cruft you accumulate and must clean up later. There's also a chance you will lose all your work if you navigate away from the page, refresh your browser, or let your computer sleep. 
• Open a ticket for help. Please ask a web editor to look over your content just before (or even just after) you post. We will see issues in HTML that you may not. It’s okay. This is our job, and we’d rather clean up now than discover issues later.
  • You have two options:
    • Email [email protected]: The ticket will be opened in the name of the emailer, but you can also cc: people who should be kept informed. To open a ticket in another person’s name, forward their email - with no comment - to [email protected]. The ticket will be opened in their name with cc: to you. If you do comment, the ticket will be opened in your name.
      
    • Visit https://cscomms.lbl.gov (help portal), login using the “Google” option and your Lab ID, and select the “open a ticket” button.

IMAGES

• Should have a descriptive file name before they are uploaded

  • Images named “Screen-Shot…” are 1) inaccessible and 2) SEO-killers, as well as being, 3) difficult to locate if broken.

  • Better names include some tie-in to the subject, title, or theme
    e.g., “Perlmutter-computer-cabinet-group-shot.png” or “PFAs-in-Soil-Illustration.jpg”

• Must have accessible-friendly alt text

  • Better alt text:

    • Describes the image for the visually impaired
      i.e. “Color graph comparing environmental observations”

    • Please do not copy/paste the entire caption as alt text

• AVOID text-wrapping (Right or Left alignment) in all instances except the featured (main) image. While an image on the right or left with text wrapping is a standard in print and looks dandy on a desktop web browser, it’s completely unviewable on a mobile device (on the websites that aren’t yet responsive, including CS and NERSC)

LINKS

• Use descriptive text 

• DO NOT USE “click here,” “here,” or “go here” or any similar non-descriptive phrase

• Avoid bare URLs 

  • Don’t: “Go to https://lbl.gov/phonebook.” 

  • Do: “Search the staff directory.”

• Scholarly article links

  • USE DOIs (Digital Object Identifiers) in the link.

  • DO NOT use Google Scholar, Google Search, or other redirector links that are not permalinks.

  • Use the article title (even if it is very long) as the link “title.” (Depending on the version, the CMS may call it a link “description,” but it’s the same thing).  If the link breaks, having the title will allow us to find a replacement link at another source.

• Other rules of thumb:

  • Prefer internal to external links.

  • Use link “from this website” and navigate the site to internal links (if the page moves, this link will not break).

  • Select “open in a new window” for all external links.

  • Minimize contextual links and avoid Wikipedia links and “definition” links. (Ask: Is this link absolutely necessary? Or could curious readers search for it themselves?)

  • Do not include redundant links on the same page or in the same article. (This includes links to the main Berkeley Lab website: We link to it in the footer of every page on every website.)

SUBHEADINGS

• Use the pulldown menu at the top of the rich text (content) editor window  to style headings in hierarchical order starting with H2, then moving to H3, etc. (All page titles, headings, and subheadings should be in “headline style” caps.)

• Use headings in order, e.g., H2>H3>H4 
  Don’t skip directly to H4 because you like the styling better or an H2 just “doesn’t look right.” Screenreader users rely on these levels as organizational signposts to navigate the page. Using them out of order can confuse adaptive technology.

• Don’t style your own subheadings, for example, by making text bold, italic, or by changing the font size.
  
  Why?

  • Screen readers (often employed by people with low vision or intellectual disabilities) use headings as landmarks to navigate the page. 

  • If subheadings are not identified in HTML, they don’t appear to be landmarks to the reader. 

  • Likewise, search engines use headings to score the relevance of a page and to index it.

• Style Q&A questions as headings so that they are visible to screen readers.

META DATA DESCRIPTION

• ALWAYS fill out the metadata description field. The meta data description is located in an expandable window at the bottom of the “content” window. You must select the arrow to open the field.

• Metadata description is important because it appears

  • On the home page, news index, and article index (article pages only),

  • On index pages (all pagetypes), and

  •  In search results. 

  • It also affects the SEO of the page.

Keep it short and to the point: One or two sentences.