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.