Sunday, June 14, 2015

SPFE: Synthesis, Presentation, Formatting, and Encoding

By Fei Min Lorente

Mark Baker was generous enough to deliver another seminar to the Southwestern Ontario Chapter. He explained why and how to use SPFE (pronounced “spiffy”), which is a fascinating architecture for anyone—professional writers and casual contributors alike—to create individual pages and let the architecture take care of incorporating them into publications. It removes the barrier of a specialized markup language or specialized interface that someone has to learn before putting information directly into a structured and self-organizing format. It’s designed for documentation that will be published on the web.

Why you would want to do this is explained in the other seminars that Mark has presented to us: Every Page is Page One and Information Architecture—Bottom Up*! To summarize, people usually find information by searching first, which means that they won’t necessarily start reading on any particular page (hence, every page is page one). This means that the top-down organization of information is mostly irrelevant. In other words, if you try to organize information in the order you think people are going to read, you’re setting yourself up for failure. Wikipedia is Mark’s favourite example of how information should be organized for maximum usability. Each page is a topic, and all the information on a page is at the same “level”—it doesn’t mix generalities with details. For details, you can click on one of the many links that will explain what you need to know.

For more reasons to look at SPFE more carefully, imagine training your SMEs to do structured authoring, without them having to learn about the publishing system or content management. To them, it will look like they are filling out a form, with field names they can understand so that they know what to write. They will have to think about the rhetorical structure and the annotation of their subjects, but they already know this information, and are simply learning to express it formally. SPFE guides their input while saving you the time of writing everything from scratch. It enables distributed authoring, which means a shorter time to publishing the most up-to-date information.

After all, customers expect accurate and up-to-date information whenever they search for it. This means that the publishing cycle has to be instantaneous. It’s one thing to collect up-to-date information and publish it at the press of a button, it’s another thing to create and maintain all the links, especially if you’re publishing a subset of the documentation. SPFE uses the semantics of the information to create links. For example, if the SME identifies something as a feature, SPFE will go looking for another page about that feature, and automatically link to it. If there isn’t an existing page about that feature, SPFE will point out that you’ve got a gap in your documentation. You can choose whether to add that information or ignore SPFE’s advice at that point.

To help guide your SMEs with their information input, you need to customize the “form” to reflect their area of technical expertise. You might do this now with a customized DTD or schema, or by using a subset of DITA, but it would be an awkward way to do it. If you have ever implemented such a structure, you know that this isn’t an activity that you’d want to do often. SPFE, on the other hand, makes this structural customization easy so that the SMEs don’t have to learn a complex and foreign markup language, while you can harness the power of structured content with metadata. You can reuse SPFE’s existing structures, which are composed of elements, leave out the ones you don’t need, change the ones you want to customize and add new ones. You can also reuse and customize the scripts that validate and automate the linked output.

Yes, there are scripts involved. Working with SPFE is not for the faint of technical heart, but if you know a good programmer, this is the most flexible documentation system available (i.e., it’s not tied to any particular tool). Mark is using oXygen as his editor, Python to manage the build process, XSLT to process the markup, and CSS to format the output for the web; however, since everything is text-based, you can choose any tool or scripting language, as long as you follow SPFE’s general architectural design and design principles. SPFE is open-source, so you are free to use it as you need.

The concepts behind SPFE are well-reasoned, but considering it took Mark three presentations to lead us to this open architecture, it’s hard to condense the information to one blog article. If I’ve piqued your interest, I recommend taking a look at the SPFE pages on the web, starting with http://spfe.info/. Oh, sorry, I’m supposed to let you choose your own first page.

*For a more complete article about Mark’s Information Architecture—Bottom Up, see Sarah Maddox’s write up.


No comments:

Post a Comment