Category: Writing

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.

Should You Learn More About The Text Encoding Initiative?

Brand new to me, looks great, and yes you should learn more about it. I will!

  • Wikipedia page

  • What is TEI? (via Wikipedia)

    The Text Encoding Initiative (TEI) is a text-centric community of practice in the academic field of digital humanities, operating continuously since the 1980s. The community currently runs a mailing list, meetings and conference series, and maintains the TEI technical standard, a journal,[1] a wiki, a GitHub repository and a toolchain.

  • What’s it stored in? XML (via Wikipedia)
  • Is there a journal? Yes (via Wikipedia)
  • Are they on GitHub? Yes (via Wikipedia)
  • Are there any samples? Yes lots of them (via Wikipedia). The TEI by Example project looks like a better place to start though
  • What are some tool-chains for it? There are surely more but I ended up here on
    • TextGrid which provides 4 interesting tools that bafflingly I can no longer find the link to.
  • Anything particularly notable about TEI? Yes!
    • “One Document Does it all (ODD) is a literate programming language for XML schemas.”
    • “ODD is the format used internally by the Text Encoding Initiative for the TEI technical standard.”

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.