Long History of Crap for UI

I've got a long history of building really crappy UIs.

Mesa

I wrote the first real-time spreadsheet: Mesa.

Mesa ran on NextStep.

NeXT had an enterprise license and used Mesa for most of its spreadsheet needs.

And I'd get periodic complaints from Steve Jobs about how horrid the UI was. Rumor had it that he insisted that people export Mesa spreadsheets to 1-2-3 format, so Steve could look at the spreadsheets in Improv.

I didn't care. I was a very self-assured 20-something and Mesa was fast and powerful... it powered automated trading systems and processed billions of dollars of buy/sell orders every day.

Lift

I founded the Lift web framework project.

I started with a "build rock solid, powerful stuff" first mentality.

Yep, Lift has the best server-push support of any web framework, even a decade after Lift was started.

Yep, Lift is still the most secure web framework around.

And Lift's documentation is weak. Over the years, some really excellent folks have worked to improve Lift's documentation and the whole developer experience in Lift-land is sub-optimal.

Folks who use Lift use it in spite of the initial challenges to learning and using it.

Sigh.

Doing it Right

I recently started Funcatron and this time, I'm going to focus on whole life-cycle User eXperience.

Modes of Learning

Different people learn in different ways. Creating an experience that allow folks to learn in a way that's optimal for them is critical to the experience. Here are the modes of learning I've observed tech folks in:

• Code Explorers -- these folks learn by reading code. The code may be sample code, framework source code, code snippets, etc. The Code Explorer will often take a piece of code and rapidly iterate on changing/enhancing the code to see what happens on each iteration. Having a broad range of small to large pieces or runnable code floating around allows the Code Explorers to learn the way they learn best.
• Visual Learners -- these folks need to see pictures and diagrams to best learn materials. Providing sequence diagrams and other visuals will help these folks grok Funcatron.
• Text Learners -- these folks parse words into an understanding of a system. Lots of text describing Funcatron, along with code examples and visual flows, will help the text learners best learn about Funcatron.
• Whole System Folks -- there's a class of people who must understand a whole system before they can dive into any piece of the system. We need overview/architecture documentation for these folks.

Documentation Types

There are a wide variety of documentation types. Here's a list:

• API Docs -- Java Docs or something similar. There are lots of automated tools for creating this kind of documentation. Funcatron will have automated API documentation for each release.
• Getting Started -- documentation and sample projects that allow a developer to get started quickly by cloning the project and incrementally morphing the project to the developer's needs. This includes Maven Archetypes.
• Operations Documentation -- Okay, how do you deploy a Funcatron powered app? How do you monitor it? When things go pear-shaped, how do you figure out why things are working unexpectedly? This kind of documentation should be consumable under high stress at 3am.
• Vision/Strategy/Architecture -- We need to let people know what the Funcatron vision is and how we are going to implement the various pieces. Going back to Lift for a minute... I was great at answering vision questions when asked on the Lift mailing list, but the vision and architecture for Lift was scattered across many blog posts and mailing list answer. Not in Funcatron.
• Reference -- In addition to API docs, there needs to be a bunch of reference documentation (e.g., message formats, wire protocols, etc.)
• Blog Posts -- Blog posts are an important mechanism for engaging the community around pieces of Funcatron and exploring particular pieces of Funcatron. However, blog posts should be explicit about versions and when possible, if APIs change or things would break, the blog posts should be marked as deprecated.
• Samples & Cookbooks -- Let's identify common patterns and problems that folks are looking to solve and create code samples and cookbook recipes to help people. Richard Dallaway did a great job of this with the Lift Cookbook.
• Prompts and Error Messages -- on of the best things about Docker is that it has a ton of extra helpful feedback. On the Mac, Docker prompts you about why it needs root privileges before OS X props up the password prompt. There are a million little nice things in Docker that guide the user to the right place.
• Greenfield vs. Migratory -- Some Funcatron projects will be greenfield... the project is new and there's no concern for compatibility with previous systems. And then there's legacy. Funcatron documentation must assume that the reader is shaving down parts of a legacy system. This means talking to J2EE, Node, Rails, etc. developers in the documentation is part of the task. It also means that we need to give readers tools they can use to make choices about how to bring their code to Funcatron.

Process & Tools

Okay... we've explored the "who" and the "what"... but the "how" is critical. We need to actually make this happen.

Between now and the Funcatron 0.2.0 release, we will write up reasonable starts for all the above documentation types as well as put in place mechanisms for generating the documentation.

Process-wise:

• Every commit/pull request must be accompanied by updates to the documentation. This was a most excellent suggestion from Peter van Hardenberg who says it works very well in the Postgres community.
• For any release, there will be stable URLs for all documentation and all the URLs will exist forever.
• Part of the continuous integration system will be the generation of JavaDocs, Clojure Docs, etc. as well as extracting the Clojure Spec information to automatically generate wire-line and other documents.
• As much as possible we will use automated tools to generate documentation which also means up-to-date documentation for the master branch.
• We will use AsciiDoctor with Diagram for generating all our documentation. This means, except for the Diagram pieces, the documents will be readable as HTML on GitHub.
• For non-release items (e.g., blog posts, sample code), review items at each release and mark anything that's changed as changed or deprecated.

Asciidoctor also allows us to generate PDF and EPUB output from the documentation so if we need to create books or other "not web page" documents, the information will

Sea Change

Yeah... this is a sea change in my approach to delivering software. But if the Funcatron contributors spend a little extra time communicating with our users, our users will save a lot of aggregate time and we will best serve them.