Is The SPFE Open Toolkit Worth Learning?

You know it is one thing to espouse the profundity of great ideas becaue talk is cheap. Its antoher thing entirely to write down what you think AND DELIVER A TOOLKIT FOR DOING IT!

Read about it here: SPFE Open Toolkit Documentation.

This is thoughtful and generous offering: a real gift.

Are DocBook and DITA Comparable?

Nailing down to the data model alone this article lays out the answers:

  • No they are not comparable because
  • DocBook lets you represent all things that you must tailor for your end goal
  • DITA lets you customize a lot of existing things, and new kinds of those things, and stay focused on the philosophy that guides it

It is a nice overview and breakdown.

Should Every Page is Page One (EPPO)?

See and read Every Page is Page One:

Every Page is Page One is an approach to information design and information architecture that recognizes that readers may enter a content set at any point, and so ensure that every page in the content set can function as page one for the reader.―Mark Baker

This is thoughtful and generous approach: a real gift.

For training and technical writing it seems obvious: Yes.

For other writing it probably doesn’t seem obvious. In fact the answer probably makes us somewhat queasy.

However for other writing the answer is: Probably Yes, more than we like to admit.

Has DITA Plateaued? Or Is It The Curse Of Success?

Has DITA Plateaued?

The question is more about adoption and job-listings. The article points out the fluctations and that makes sense. From that perspective though:

  • Does it mean the tech is stagnant?
  • Does it mean the tech is failing?

From an outsider perspective maybe, but from my research: DITA is thriving.

The problem is: The Curse Of Success

In the normie world when you “get it right” and it doesn’t need to change much then generally it is considered a success. For example the periodic table is somewhat controversial but overall it is a good system. Additionally recipes for classic food work because well, they don’t change much: they are classic. Are these horrible analogies? Maybe, but I think you get the point. For techies it is another story though.

For techies the measure technology of success typically quantified in either mass-recognition or job-postings. That is a fine way to measure it because it must be measured. However it is uninspiring: it doesn’t capture what the rest of the world would call success. Any more tech examples you ask? Certainly!

  • Berkeley Software Distribution (BSD) progeny suffer the fate of success. For example OpenBSD’s design-stability is often ignored beyond mentioning that it is the source of OpenSSH.
  • When there aren’t code commits for a few months on Org2Blog questions arise of whether or not the project has died. Come on: really? There aren’t always new features to add or bugs to fix (or time and manpower to fix them.)
  • Thousands of tiny-projects suffer the same hilarity Org2Blog faces: success and stability generally alarm people.

DITA on the other hand, surely there are flaws, but overall my research says things are looking good despite The Curse Of Success.

Darwin Information Typing Architecture (DITA) In A Few Words

DITA is a philosophy for topic-oriented information management along with structured document data definitions for delivering it. It isn’t a general-purpose reusable technology like DocBook. Instead it focuses exclusively on creating a document model that best serves the diverse needs of your readers across different and equally valid scenarios.

A lumpier way to put it is that DocBook is to DITA as a chicken egg is to an omelet. You can’t unscramble an omelet, and when you figure out how, you shouldn’t! You can use DocBook to provide a DITA-like approach but you can’t use DITA to provide DocBook’s functionality.

How do DITA and DocBook compare? They don’t is how.

DocBook is an open-ended technology for designing anything. DITA is a focused technology for delivering a learning model.

An open standard created and maintained by self-sacrificing volunteers and BIG companies it is beloved, high-quality, and suffers the same ills and pangs of all human endeavors

DocBook In A Few Words

DocBook is a semantic markup language used to both define documents as structured data (and its elements ) along with explaining the meaning of those data (and its elements.)

The domain of the documen structured data is completely open and unlimited meant for 100% definition by the user.

It publishes to just about everything.

An open standard created and maintained by self-sacrificing volunteers and BIG companies it is beloved, high-quality, and suffers the same ills and pangs of all human endeavors

MkDocs: Project Documentation With Markdown

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Looks like a nice static website generator.

Its intended for project documentation but looks fine for any topic based writing.

Pandoc A Universal File Markup Language Converter

If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Need to generate a man page from a markdown file? No problem. LaTeX to Docbook? Sure. HTML to MediaWiki? Yes, that too. Pandoc can read markdown and (subsets of) reStructuredText, textile, HTML, and LaTeX, and it can write plain text, markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, textile, groff man pages, Emacs org-mode, EPUB ebooks, and S5 and Slidy HTML slide shows. PDF output (via LaTeX) is also supported with the included markdown2pdf wrapper script.

Pandoc understands a number of useful markdown syntax extensions, including document metadata (title, author, date); footnotes; tables; definition lists; superscript and subscript; strikeout; enhanced ordered lists (start number and numbering style are significant); delimited code blocks; markdown inside HTML blocks; and TeX math. Other options include “smart” punctuation, syntax highlighting, automatically generated tables of contents, and automatically generated citations (using citeproc-hs). If strict markdown compatibility is desired, all of these extensions can be turned off with a command-line flag.

(via pandoc)