Documenting the Undocumentable

I think a lot of developer tools come with exactly the type of statement the author is looking for--"what the developers were thinking when they designed it...the assumptions that were made about how the program should be used." I too would also enjoy it if people started doing this for ordinary software as well. But I think I know a reason why they don't.

The author raises the example of Microsoft Word, so let's imagine we were going to write such a statement for Word. The problem is that we'd end up writing something that would piss people off. The author says this: "Why is it so much work to change the fonts in a paper written in Word? Because you shouldn't be setting fonts directly; you should be using paragraph styles to signify your intent and then make visual adjustments later." But when I look at word's interface, it doesn't look like word was designed with that philosophy in mind at all. He's right that using styles instead of setting fonts directly will make it easier on you later, but that clearly wasn't Word's philosophy.

If you want to directly change the font or style of just the one piece of text you selected, there are multiple toolbar and menu widgets, highly visible and available, as well as multiple shortcut keys. In office 2007 they added the "live preview" feature to make it really smooth while you're doing it. They clearly went out of their way to make these types of direct changes really easy and really discoverable.

On the other hand, if you want to define a new style, or change one of the styles that is already defined, you have to do through multiple layers of nested modal dialog boxes. Once you have done this, using the style is made easy and highly available (lots of ribbon space, etc.) But again, the easy action is a purely local action--it operates on only on the text selected.

So to me it looks like word's philosophy is: you should be able to visibly see ALL the results of what you're doing right as you do it. Anything that violates this rule gets set aside in a dialog box so that the ordinary folks won't hurt themselves with it. That can make things really frustrating when you're editing a large document and want to keep things consistent across it, but they'd rather make their tool easy to understand upfront, even at the expense of larger scale advanced use. Other tools that are intended for mostly professional use, such as Photoshop, make the opposite choice--they allow their interface to be less obvious at first in order to make it easier to use at an advanced level.

The kind of philosophy statement the author is looking for would end up making that type of tradeoff pretty obvious, even if it managed to avoid stating it explicitly. And most people won't want to do that when they're thinking from a marketing perspective. They never want anything that states, or even too strongly implies, that their tool has a drawback--even if it's one that was accepted on purpose to get a better benefit elsewhere. I'm not arguing that this is (or isn't) the right way to approach marketing--but I can say it's easy to observe this mindset across many different fields, including our own.

First thing I thought about when reading this was the classic tree swing picture set of what the user wanted, what the developer did etc etc. The type of documentation your on about, ie the devlopers logic and resoning behind the software, ie the mentality/mind-set folled at the time is a fasicnating insight. Sadly with commercial software we have historicly been shut of from any insight and beyond the devlopers names hidden in some easter-egg crits page burried deep in the software we never realy knew. One of the main reasons is companies wanted to hide there developers and code secrets to maintain there advantage in the market. Now todays market is more open, more about the product being good and not how it is marketed as much (though that still plays out). So we can read up from individual developers in there blogs and thankfully for many companies encourage that aspect more as it is seen as good PR marketing and gains sales/face with the public.

In the past we did also have alot of tue computer magazines with technical articles that would still cut it today. This entailed quality interviews and some good insighful questions. Then computer magazines all started turning into wanabe Which magazines and targeted people wanting to learn about computers but still fail to operate a VCR. This turned magazines today into something the hacker mentality geeks would not touch. But we had the web then, so with that many more quality articles direct from the developers started to appear. We all have heard about John McCormack of Doom fame, not as much due to Doom, but in that he gave alot of good interviews with technical knowledge that allowed you to more closely follow his mindset.

Another aspect of note is alot of software years ago was all optimised for size and speed as it was more a limitation than we have today and with that many short-cuts impacting how the user intereacted had more chance of going thru than not. Nowadays it is more design driven by customer feedback than not, but it is often a balance of work/effort (heck I see American English as a option in so many software packages and no British English, not as bad today but still noticable shortcut in design).

There is also the case that say finger in the air that every developer in the World working on a commercial project has at some stage in the life, had to make a design change not based on time. Be it a cut-off date, release date/target. Many cases and for some software you notice it as they have more bugs and this is why many people prefer to not touch intitial X.0 releases and wait until a few sub relesaes have passed, 3 being popular given there was no service pack 3 for vista and win7 yet was for windows XP but that is a bad example yet valid for many.

So with all those factors many developers don't have the time to dig in and also the type of code documentation has not evolved in a way that mandates it beyond standards and in that the most readable computer language we have in use today would safly be COBOL. So from developers point of view, unless they solely work on a area of code then they have a hard time documenting it for there own use let alone doing a blog about it.

Sadly some of the best ones would be the reminise type story's from developers of years gone by and by this I mean they seem to tell things with a hint of hindsight thrown in and are able to say back then we did this, and I still shudder today why given we know this and that now. You don't get that level of insight that you get with a ongoing blog from developers, so you miss out on them being able to talk about the code and what they did and why as a complete application perspective and will never get that retrospective viewpoint that is often: we did this, it seemed all the trend back then and nowadays we would be taken out and shot for even mentining that approach.

So in short things are better than they once was for developer insights but the best developer insights are the retrospective ones when they can admit to this approach to being wrong and that being ahead of its time etc.

As for manuals and missing out on all that handy hardcopy I agree it is a sad loss, though at least today you can get it updated and corrected much quicker and are able to use search to find that page you want without playing index lookups manualy with ...paper.

Though the market for books(physical and ebook format) for learn X in 24 hours or a dummies guide that explain the software from a fixed mindset instead of the generalised approach taken by formal documentation. You also have advanced guides and tricks and tips style books for those wanting something more at there level. That has always been the case but the feild is somewhat larger than it was and always growing.

But I did like the nice foot_ pile of manuals with some software, made paying XXX amount seem more palatable as apposed to today paying XXX amount and being pointed to a URL which you download the software and for XX more you get a copy on a disc and still no manual to swat flies with.

Still another aspect about today is that you can usualy twitter the developer team or failing that get enough friend emoing on facebook and the developers not only talk to you but have to listern to recoup PR. But users bullying developers is and always has been a two way process.