Zone: Web Dev
TLDR: How can a tool with a great concept and a great user interface
ultimately fail in its promise? By taking the wrong path in just
a couple big ways.
Markdown All the Things
In my effort to convert all my documents to Markdown,
I have been looking for a tool that would allow the use of Markdown
for larger technical documents (the kind of thing traditionally done
in Microsoft Word). I have been looking for two main features: first,
word processor like behavior with Markdown (to simplify adoption for
new users). Second, a “project” organization concept (to gently ease
people who are used to editing a document into editing multiple
individual files that are assembled). The latter item I think is
very important for documents that are built iteratively, over time,
as otherwise it gets difficult to see and review changes.
For this reason, I was really excited when I saw that GitBook has
an editor that is cross-platform and provides both the items
I mentioned above. Unfortunately, after exploring it, it ended up not
being usable for my particular case. I strongly considered not writing about
my experience, or writing about it in a generic way that didn’t explicitly
reference the tool, but I concluded that there are enough positives from
my experience that I can write something balanced, and the negative parts
of my opinions might have broader applicability.
Judging a GitBook by Its Cover
Since I am going to be a little negative in parts, let me start by saying
I love the concept of GitBook. As someone who wrote a small book in
Markdown, committed to a Git repository, of course I’m likely to feel
positive toward it. But I also like that they have an online editor, a
platform for publishing, and have done some good work to make the toolset
accessible to a wide audience, not just those of us who choose to write
articles in Vim. If you’re interested, and especially if you can
use the online editor, I encourage you to give GitBook a try.
On downloading and running the editor, I hit a few unfortunate items right
away. Rather than opening a blank document, the first screen is an offer to
login to a GitBook account. I recognize that GitBook would prefer to get
people signing up for accounts on the website, but being solicited first
thing into a program is unpleasant. Worse, the program doesn’t appear to
check the network state, so if I’m offline I still get presented with a login
button, but clicking it brings up a blank screen. This brings me to two
important user interface rules:
- Don’t assume your preferred use case is your user’s preferred use case.
- Even modern computers are offline sometimes.
Clearly the preferred use case for GitBook Editor is to use the program while
fully interactive with their servers. And of course a key reason for making
an editor that can be installed locally is to convert users into signups. But
those signups are not going to happen if someone is presented with an unusable
login button as their first impression of the program.
To their credit, there is a “Do This Later” button on the startup screen.
Unfortunately, “later” means “the next time the program is run” and “the time
after that” and so on. Which means we need a rule:
- Preference settings are not just for preference dialogs.
Users express preferences sometimes by the choices they make. In this case, my
choosing to defer signing into an account could be saved as a preference, maybe
with a dialog that tells me where to go to do it later. (In this case, there’s
already a permanent login button in the corner of the main editor, so there’s
no concern I’ll forget how to do it.)
Friendliness and Configurability
At this point we’ve gotten to a nice library screen. This is a positive, in that
it recognizes that finding previous work is a hassle, and there’s real value for
a program to keep track of previous work and present it in a friendly way. At
this point, I noticed both an “Open” and an “Import” button, which was a little
confusing and should have been ominous. (Foreshadowing…) I had a few existing
Markdown files, so I tried the “Import” option. In came my files, and I could see
my new project in the library and click it to open the editor.
At this point, I was delighted by some of the functionality. The sidebar includes
both a Table of Contents and a Files Tree; the Table of Contents is built from
- Don’t be afraid to present a user with the same information, organized in
different ways, as long as the difference is clear.
Depending on whether the file organization matches the book’s organization, there
might be a lot of duplication between the two lists, and I can see where presenting
both could be confusing. But the two views are different, and especially since
it’s possible to have files that aren’t in the summary, keeping both is a smart idea.
I started editing and saving, and then started looking for the button to commit
my changes to Git. When I didn’t find one, I started looking through the available
buttons and settings, and discovered that the default behavior is to commit changes
to Git on every save. This doesn’t work for me, because I would like changes to
be bundled together to make them easier to review. But I don’t really mind, because
I understand the motivation in hiding that from new users, and it’s a configurable
- Power users don’t mind customizing their preferences, as long as you make the
settings available for them to do so.
And Full on the Town He Fell
After a few more edits, I switched back over to a terminal window that was open
to the original location where I had my files. And here’s when things
started to go horribly wrong. I looked at the local file system, and none of my
changes were there! I started to realize that “Import” meant “relocate these
- Don’t relocate your user’s files.
- No, really, just don’t.
- OK, you shouldn’t, but if you have to, please tell them exactly what you did.
Nothing is quite as disconcerting to a user as the idea that a program lost
changes that should have been saved. Even once you figure out that the files
are not lost, they are just somewhere else, you never really trust a program
the same way again.
I eventually found the files, conveniently hidden in
With relief, I moved into that directory, and started looking at both the local
files and at
git log. Imagine my horror when I realized that even in that
directory, the working copy of my files didn’t contain my most recent changes!
Sure, the changes were there in
git log, but they weren’t reflected in the
files themselves. Worse, since I turned off auto-commit, when I made changes,
saved them, but didn’t commit them yet, they existed in some nebulous state,
neither in the working copy nor in the index.
This behavior is completely inexplicable to me. Why insist on relocating an
imported project into your own directory, unless it’s because you want to be sure
you completely control the changes to the files? In which case, why leave files
at old versions? As just one small example of the horror that results, this approach
git diff HEAD actually shows the opposite of my most recent commits,
because the working copy is older than HEAD!
- Don’t confound your user’s understanding of how computers work.
- You don’t own those files, the user does.
In his discussion of the Unix philosophy, Eric Raymond talks about assuming
that the output of one program will be the input of another, and about preferring
text streams, because they are universal. The fundamental idea beneath these concepts
is to not assume that your program is the only way that the user will interact with
their data. Locking a user’s data in a database or hiding it in an inaccessible
place on the filesystem is an anti-social practice. It might be necessary to store
data in some inaccessible place or internal format for performance, but what comes
with that is a responsibility to provide a way to get the data back out again, in
some widely accepted format. And if your whole premise is editing files in a
human-readable plain text format, and storing those files in a well known version
control tool, you really need to be making those files available in exactly the
same way that a user would see them if not using your tool.
At this point I concluded that, as much as I liked the concept, there was no way
I could ask my teammates to use GitBook Editor. I envisioned the confusion that
would be my responsibility to handle, as people tried to figure out how to
get at their documents without going through the tool. At the moment, I’m left
without a perfect solution; there are great Markdown “word processors”, and great
editors that manage multiple files in a project, but nothing that quite combines
the two. But I have hope for the future.