SPFE Documentation | Collections > SPFE Open Toolkit Documentation

SPFE Open Toolkit Documentation

The SPFE Open Toolkit is a toolkit for building content creation systems using the SPFE architecture.

The SPFE architecture is designed to facilitate the creation of structured writing systems that use a bottom-up information architecture.

Bottom-up information architectures are common on the Web. Both wikis and blogging platforms, as well as many Web CMS work on the bottom-up pattern. However, there are no bottom-up systems based on markup-based structured writing principles (some database-based structured bottom-up systems exist). The SPFE Open Toolkit is designed to fill this gap.

The SPFE-OT is also capable of creating top-down and hybrid top-down/bottom-up information architectures.

 

The current state of the SPFE documentation

The SPFE documentation has been developed to date as a testbed for the SPFE Open Toolkit. It is not complete and it may contain information that no longer describes the current state of the toolkit or the accompanying schemas.

The biggest questions you probably have about SPFE are why it was developed in the first place given that we already have so many structured writing tools such as DocBook, DITA, Markdown, reStructuredText, LaTeX, and ASCIIDoc. The best answers to those questions are to be found in two books I have written. (Both books came about, essentially, to explain why SPFE, and writing the two books has delayed work on SPFE itself for a long time. The books are:

The Every Page is Page One book describes an approach to information design which I call bottom-up information architecture, which is based on the user behavior of finding content principally by search, which can throw the reader into any page in a content set (thus, Every Page is Page One). Fully supporting this requires an approach that makes every page work as the first page the reader sees and supports adequate navigational aids for readers to move onward to other topics they may need. Wikipedia is an excellent example of a bottom-up information architecture. Most current structured writing tools do not support bottom-up information architecture well. (Wikis are bottom-up by nature, but also unstructured.) SPFE is designed to support the creation of bottom-up information architectures.

The Structured Writing book provided an overview of structured writing techniques and systems, but it highlights an approach to structured writing which I call the subject-domain approach. Most current structured writing systems are either wholly or principally document-domain systems. The subject domain approach has many advantages, both in terms of rhetoric and process, and it is particularly advantageous when creating a bottom-up information architecture. SPFE is designed to support the use of subject-domain structured writing.

The SPFE documentation is intended to be an example of bottom-up information architecture, but it isn't there yet. My intention is to return to the SPFE documentation once the Structured Writing book is complete.

 

The role of SAM

Along the way, the writing of the Structured Writing book gave birth to another project, to develop a alternative markup language for structured writing. The vast majority of structured writing today is done in XML using a structured XML editor which presents a pseudo-WYSIWYG graphical editing environment to the writer. This is inherently a document-domain writing environment. It has many problems even for working in the document domain, but it is even more difficult to work in when writing in the subject domain. Many people today prefer to work in lightweight markup languages such as MarkDown which you can create easily using a simple text editor. However, all current lightweight markup languages are simple document domain languages. There was no lightweight markup language that could be used to create specific subject-domain semantics for writing about specific subjects. Something new was needed to make writing in the subject domain easy for writers.

For this purpose, I created SAM (Semantic Authoring Markdown, or Semantic Authoring Markup as you please). The Structured Writing book is written SAM and used SAM for most of its examples. You can find SAM at https://mbakeranalecta.github.io/sam/. SAM is not intended to completely replace XML, which is more general than SAM and works fine for most of the things it is used for. SAM is intended as a front-end authoring language for structured writing systems that would still use XML internally. The current version of SPFE is still basically and XML-based system and will remain XML based in all of its internals. It has basic support for SAM as an input language, and this will be expanded so that SAM will become the main way to write content in SPFE. XML will always be supported as an authoring language as well, however. It is part of the design intent for SPFE that it should be as catholic as possible in the formats it accepts.

 

Writing in a SPFE Environment

SPFE is intended to make structured writing as simple as possible for writers by minimizing how much they need to understand about the publishing system, and by minimizing the need to understand to interact with the overall body of content that an organization maintains. Traditional content management approaches of ten require substantial knowledge of both the system itself and the whole corpus of content in order to participate fully in content creation. SPFE is designed to avoid this by creating a publish and content management environment that is driven by metadata about the subject matter of the content (subject-domain markup) -- something that the author naturally understands.

Structured authoring is also easier if the structures that authors are asked to create are simple and related as specifically as possible to the subject matter they are writing about. SPFE is designed to work best with small subject-specific structures, and to make it as easy as possible to design and implement such structures.

 

Schemas

As a structured writing system, SPFE works with content that conforms to a set of formal rules known as a schema. Schemas define which content structures can be used in which situations. Successful processing of content depends on the content conforming to both the letter and the spirit of the appropriate schema.

However, unlike the DocBook and DITA systems, SPFE is not based on a particular schema. Rather, SPFE is a modular content processing architecture that can be used with a variety of schemas. However, SPFE does make certain presumptions about how schemas will be written. In particular it expects a declarative style of markup in which the document markup does not contain any publishing or content management directives.

To enable users to get up to speed quickly, and to provide a baseline of functionality for building SPFE-compatible schemas, SPFE Open Toolkit includes the EPPO Simple schema set. EPPO Simple is a highly modularized set of schemas and associated processing that you can use directly or as the basis for creating your own schemas.

 

Installing the SPFE Open Toolkit

The SPFE Open Toolkit is available on GitHub at https://github.com/mbakeranalecta/spfe-open-toolkit.