Good documentation is the definition of empathy

So a few people have started using DasBlog Core and could not be happier! It is mostly folks who are remembering the old days of the DasBlog classic and yearn to get that content back. By far the most rewarding comment I have received was how easy it was to simply copy the old Content folder into .NET Core and everything magically works. Of course that was the whole point, but I am glad to see that work validated with bloggers of yesteryear.

I have lots of features to complete … I mean a lot, however, I think it is imperative to take a step back and start focusing on the documentation.

I recently split the wiki pages up as a first step:

• Deployment
• Configure your blog
• Create a blog post
• Designing a theme
• DasBlog architecture
• TagHelpers & Partial Views
• Migrating from DasBlog

What I am trying to do is imagine where someone, adopting the tool for the first time, might need help. I am attempting to look beyond what I know (almost without thinking now) and imagine what it must be like to approach installation and configuration without any of the background I take for granted. For me this defines how empathy should be employed in technology, by considering the experiences, feelings and thoughts of others.

In many ways it was the process of defining documentation that made me realize some of the practical limits of the DasBlog Core project. For example, I had assumed that editing my config files manually was a reasonable compromise, however, after trying to document some basic steps it became clear that my assumptions were naïve. I literally reordered my backlog of work to make it easier to document critical steps which in turn made it easier to use.  My conclusion is that If you cannot explain a concept in a few short paragraphs, it is just too complex, and needs to be refined and possibly even redesigned.

I love the quote “The limits of my language mean the limits of my world” because it expresses succinctly the idea that our skills in developing accessible language (documentation in this case), can limit our effective engagement with the world (or product).