
Documenting the Undocumentable - prajjwal
http://prog21.dadgum.com/161.html
======
ChemicalHarm
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.

~~~
ams6110
Do most people actually use Word for large documents? Or is it mostly short
letters, memos, etc. where paragraph styles would be overkill.

I myself would never consider Word for anything over about 2 pages, but I'm
guessing I'm in the minority on that.

~~~
spc476
A friend of mine used Microsoft Word to write a few books. Each book was a
single file, and he would bitch about the problems all the time. I think he
still uses Word.

~~~
yen223
To paraphrase Churchill, Word is the worst text processor, except for all
others that have been tried.

------
Zenst
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.

