Technically Speaking

I’ve been using StumbleUpon for a while now. It is a tool that takes the concept of “surfing” to a whole new level. When you first join, you tell StumbleUpon (SU) areas that interest you. Then you click the Stumble button (I use a Firefox extension, so the stumble button is always visible on my tool bar). Based on the areas that interest you, SU takes you to a site. Once there, you evaluate the site. If you like it, you give it a thumbs up. If you don’t, a thumbs down. Then you Stumble again. SU builds a profile based on sites you’ve marked that you’ve liked, so it gets better at finding new websites you should like.

Today I Stumbled across a blog entry that points to fifty tools which can help you in writing. The blog originally (2005) pointed to Poynter.org, where the articles were published. In 2006, the articles were removed from the Poynter website, and now the blog entry in question points to the Internet Archive at archive.org.

The list of tools is fascinating, and the tips in the tools are great. I’m hoping that the book “Writing Tools: 50 Essential Strategies for Every Writer” (by the same author) gives the same info, because I’d love to have a physical copy of the rules.

While at poynter.org, I subscribed to a writing tips podcast, as well as for a writing tips newsletter. I’ll haven’t heard the podcast yet, nor have I received a newsletter yet, so I’ll let you know how I like those after I’ve had a chance to evaluate them.

Anyway, I thought I’d share a great writing tools website that I found while stumbling, in the hopes you might find it interesting too.

Now I’m off to my next Stumble…

This is the second in a series of posts on structured authoring.

In the previous post, I discussed the definition and benefits of structured authoring.

A quick reminder: structured authoring is means separating content from its format, and designing your document in a way that you
can easily add/change format to any particular part of your document. Think of it as filling out a form.

I had planned to start talking about tools right away, but I thought it would be important to first give a concrete example of a structured document. Regardless of the tool you choose to use, the process of creating a structured document is the same. Before you even open a software tool, you have to sit down and determine what content you want in your document, and figure out what structure that document has, either inherently, or can be applied to it.

Examples are best here, so let’s take a specific type of document and look at the inherent structure that exists. We’ll use a resume as an example.

Regardless of how you format a resume, it is comprised of a couple of things: your name, your contact information, and various sections that pertain to your jobs, education or experience.

With a structured writing approach, we will call each of these items “elements.” Some elements, such as name, only appear once in a particular document. Other elements, such as section will occur multiple times.

Here are some basic rules about a resume:

• There is a name element. It can occur only once.
• There is a contact information element. It can occur only once.
• There is a section element. It can occur as many times as needed.
• Sections are comprised of what we’ll call “experience” elements. An “experience” in the Education section would be a particular school you attended. An “experience” in the Work Experience section would be a particular job. Each section may include multiple experience elements.
• An experience element is comprised of a title, location, start date, end date, and a description.

Here is an example:

Name: Barrie Jones
Contact Information: 456 Anystreet, Moscow, Idaho, 208-800-9000

Section: Work Experience
 Experience: ACME Corporation
  Title: Summer Intern
  Location: London
  Start Date: June 2008
  End Date: August 2008
  Description: Office secretarial work including preparing and distributing meeting minutes, filing, and document editing.
 Experience: ABC Publishing
  Title: Editor
  Location: New York
  Start Date: September 2007
  End Date: June 2008
  Description: Edited manuscripts of to-be published books.

Section: Education
  Experience: Johnsontown University
  Title: BA in English
  Location: Johnsontown, Idaho
  Start Date: September 2002
  End Date: May 2007
  Description: Graduated summa cum laude; National Honor Society member; Dean's list for four semesters running


Now you’d probably never turn in a resume to a potential employer in the format above, but by doing this exercise, you’ve been able to identify the content in your resume that is similar to all other items in your resume. You’ve separated the structure from the formatting.

You should note that I used generic terms for all my elements. I used the general “section” in place of “education” or “work history”. I used the general “experience” instead of “school name” or “employer name”. I did this intentionally, because it allows me to re-use the section in a different way, while applying the formatting to only one element. When it comes time to format, all my educational institutions will match my jobs, in terms of formatting, which will give me a nice, balanced resume.

Once you have a structure in mind, you can figure out what other sections you want in your resume, and you can see if you need additional elements to represent that content, or if the elements you’ve defined are sufficient.

For your resume, you may want to have a section on software tools. This section might fit in this structure:


 Section: Software Tools
  Item: MS Office 2007
  Item: OpenOffice
  Item: MadCap Flare
  Item: Adobe Photoshop CS2
  Item: Adobe InDesign CS2

 Section: Awards
  Item: Rhodes Scholar 2002
  Item: Eagle Scout 2000

 Section: References
  Reference: George Bush
   Reference Address: 1600 Pennsylvania Ave, Washington DC
   Reference e-mail: president@whitehouse.gov
  Reference: Albert Einstein
   Reference Address: 1234 Big Bang Ave, Cosmos
   Reference e-mail: albert@theoryofrelativity.net


Notice again how I used the generic element “item” instead of “tool” or “award”. Again, that allows me to reuse the element and apply the same styling.

I have pieces of my References section, however, that don’t match any other elements in the document, thus they get their own names so I can style them separately.

You should also note that when I pick an element name, I’m picking a description of the element, as opposed to the eventual formatting I want to place on the element. In essence, I’m describing the structure of the content. Remember, we are trying to separate the content from the formatting.

Once you’ve got a good structure in place, you are ready to pick an authoring tool. Future posts in this series will discuss various authoring tools, and show you how to apply formatting to the content using the features in that particular tool.

We’ll keep referring back to this resume example to show you how you can format this data using different authoring tools. Stay tuned!

Today I begin a series on structured authoring, a topic of particular interest to documentation professionals (and which you may find tedious, if documentation isn’t your thing; that’s okay).

We start off by asking the obvious question: What is structured authoring? I’m glad you asked.

Here is a definition from sct-sf.org: “Structured authoring is a method of writing and arranging content that relies on rules and automatic validation to enforce the rules. Structured authoring separates content from presentation; information is labeled according to its purpose. [...] This type of writing may restrict or constrain you at first, but it saves time in the end by forcing documentation to be complete, consistent, and designed for re-purposing. Writers spend time on content and are no longer permitted to apply formatting. [...] Benefits of structured authoring include improved document quality, improved author productivity, and enhanced content sharing and re-use.”

Take for example a Master’s thesis. A Master’s thesis has a pre-defined format that is rigid. There must be a title page, followed by an optional copyright page. There must be a table of contents, and an abstract, but the acknowledgments page is optional. There are five chapters to the document. The first chapter is the introduction to the thesis. The second chapter is the review of literature. The third chapter is the definition of the current study. Chapter four is the chapter where you discuss the results. Chapter five is the conclusion.

Within each chapter there are generally (up to) five levels of headings. Each heading can contain things like body text, bulleted lists, images, and tables.

In essence, you have a document that is adhering to a structure that you can predict before you even read it.

Structured authoring has a number of potential uses. It helps documents written by separate authors to maintain structural consistency. For example, I first encountered structured writing when I worked at the MTC. I was documenting second-language acquisition software, and I defined a very rigid document structure for the design documentation for the various activities available in the software. The documents all began with a heading that was the name of the activity. Next there was a screen-shot from the application showing that activity in use. There was a heading called Instructions. In this section there was text directed at the learner, giving them instructions on how to use the activity. The remaining sections had specific titles, with matching content.

In this case, you always knew which headings were going to be in the document in what order. You could predict the content within the headings. The document had a very rigid overall structure.

So, at the MTC structured authoring was great because it gave us a professional look and feel across every activity document. Regardless of the document’s author, the documents all followed the same predictable, professional pattern. Thus, structured authoring is one way to allow multiple authors to work on the same project while ensuring consistent output.

Another benefit from structured authoring is that it allows writers to us authoring tools to provide consistency across multiple documents with regards to formatting and design. Generally, a document that is structured uses a style sheet of some sort for formatting. In most programs, you can have an external style sheet that you can reference for your styles.

In the case of the thesis, you can just write using H1, H2, H3 tags, etc. When the time comes, you can format your H1 style to appear a certain way, and all corresponding H1 text changes to the new style. Make changes in one place, and all documents that link to that style sheet are automatically changed. And because you are enforcing structure on your documents, you know that the styles will work where you expect them to.

I’m sure you can see how when you are working in a large document, or in multiple documents how using structured styles allows you to make style changes much easier as the project evolves or as needs change.

If you are new to structured authoring, you are probably wondering how to start writing structured documents. In later posts in this series, I’ll explore how to write structured documents using a variety of tools out there. In those tool-specific posts, I’ll point out the strengths and weaknesses of each of the tools.

So that is your introduction to structured authoring. You maybe aren’t familiar with the term, but I’ll bet the concept isn’t totally foreign to you. Stay tuned to posts in this series to see how you can use structured writing techniques in your favorite software programs.

Thanks for your patience while we have been down and out. We had some trouble, initially, as we switched from one server to another, and then I was on vacation for a while and didn’t get back to the blog.

But today we’re back and ready to go!