Mark's Blog

November 01, 2006

One more time from the top

Okay, I'm about ready to try blogging again. But not here. Here.

Not in the same way. No running log, no daily posts. Nothing coherent necessarily.

Posted by Mark at 02:50 PM | TrackBack

March 08, 2006

Open book

After rereading Castaneda's last book recently, I found a Digg for Lucid Dreaming caught my eye. Lucid dreaming is having a dream in which you know you are dreaming, from which point you can potentially direct the dream and imagine you do amazing stuff.

Anyway, the interesting thing is the Wikibook behind that link. It's more than the usual article. People have created most of a book there.

Remember, you can edit any page to add information — simply click on the “edit” tab at the top of the page. Your changes will be visible immediately, but don’t worry if you make a mistake, since other users of the wikibook can fix things for you if you do something wrong.

That sounds like an interesting approach to documentation. Guess I'll go dream about that now.

Posted by Mark at 09:59 PM | TrackBack

February 27, 2006

Tech documentation fundamentals

Bob DuCharme has written a succint description of the documentation you'll need for your next product. In a very small nutshell, you answer Bob's questions:

How do I get up and running with this product? How do I make the product do this particular task? What will that aspect of the product do for me?

He's right that the hard part is answering the middle question. Most of the software I've doc'd is aimed at people who build and manage systems. Often the list of tasks you have in the beginning is oriented more towards problems the product creates for the user -- things you have to do to get the product to do anything at all or at least anything interesting; things you know how to explain -- rather than problems the user had in the first place, the problems that brought the user to your product.

The real value we can provide then is in understanding real tasks a user's trying to accomplish, and showing how to do those. Are we writing the task-related docs too early? Perhaps in many cases we should plan for the User's Guide part to grow only after we've finally understood what users are trying to do.

Posted by Mark at 06:30 PM | TrackBack

January 18, 2006

What you would write about

Paul Graham posted an article recently, How to Do What You Love. His article's not bad, though it hasn't answered the question for me.

He does help me understand why I'll never be a real writer, meaning someone who writes fiction. Not only am I not a very good liar, but I also don't work at it. I find myself writing blog entries, email, tech docs, not stories.

There's a story to tell. It's about a competent, promising technical writer gradually wading out into the deep end and eventually losing touch. The technical writer is either investigating why the rate of technical writers falling psychologically ill stands so much higher than the rate for those doing other jobs, or perhaps seeing the problem from the inside.

Over the year end holiday I started writing notes about this story, but couldn't see the situation clearly. I realized it would have to be written in the third person. That set me back a while.

I also realized while scribbling notes on paper with a real pen that writing at the computer leaves me distracted. I have difficulty thinking. Blogs, email, tech docs are all compatible with attention deficit disorder. Thinking through an elaborate lie is not.

Posted by Mark at 08:50 PM | Comments (4) | TrackBack

January 12, 2006

Moment of wisdom

There's a lot of crap on Slashdot.org, but occasionally somebody writes something intelligent:

If people wanted quality, Budweiser would not be the King of Beers.

Posted by Mark at 09:15 PM | TrackBack

January 08, 2006

Replacing central planning through subsidiarity

One of the ideas spread by Peter Drucker among others was that central planning's not very well adapted to the system we have today. The principle of subsidiarity -- top Google link today; I know nothing at all about Acton or Bosnich or their ideas -- gets us more effectively and efficiently to better results. There's no point in communication all the way up a hierarchy and all the way back down if the decision affects only a few parties communicating peer-to-peer, and those few parties understand all the relevant facts.

Notice subsidiarity doesn't prescribe eliminating all centralizing aspects of planning, just the aspects that reasonably can be done with smaller, simpler, decentralized structures. There may be some activities better coordinated centrally. Many sense a tendency, however, especially among those reaping benefits out of planning centrally, to overemphasize the number of activities requiring central planning. I'm one of the people who senses that tendency. That sense reinforces my feeling that republican forms are imperfect. They cannot take subsidiarity very seriously in practice.

What sort of a system would take subsidiarity very seriously in practice? I haven't experienced one yet. Some say we already have the best possible alternative, market-based republican democracy. We may have the best alternative of what already exists, but is it the best possible alternative? Or can a more subsidiarian system exist?

This reminds me of the old joke about the mathematician, the physicist, and the engineer. The three get jailed by an evil tyrant. The tyrant leaves them in their cells with nourishment in tin cans, but with no utensils to open the cans. All they have are whiteboards and whiteboard markers. The tyrant goes away and forgets about them.

A month later, the tyrant comes back to see who's survived. He finds the mathematician dead from starvation next to a whiteboard proof showing how a tin can be turned inside out through any point on the tin's surface.

The physicist is dead as well. The whiteboard is covered with equations, and there's a tiny slit in the top of one of the cans, but the pieces of food inside were too big to get through the slit.

In the engineer's cell the whiteboard bears a few seemingly unrelated doodles. Various tins have been bashed open. The food has leaked out and smeared onto the floor, ceiling, cell bars, and so forth. The engineer is alive though.

If a more subsidiarian system exists, there may be some worthwhile time spent thinking about it, but there may also be a need for heavy prototyping. Who knows how violent the prototyping would need to be. With luck any necessary violence could be directed at inanimate tin can-like things. The proof would be in survival at the end. The problem might well look unsolvable initially.

As Gilles said the other day about the problem of getting a globally unique value from a weakly synchronized distributed system, the general case is not solvable. But all the specific cases end up either being solvable, or the problem gets redefined.

Posted by Mark at 09:33 AM | Comments (2) | TrackBack

December 23, 2005

M is W upsidedown... well almost

Some of you notice that the little icon at MCraig.org is a serif M, reminding you of the Wikipedia.org serif W, which is actually a double V. Of course that was carefully planned like movie Satanists using upsidedown crosses.

Wikipedia delivers a valuable encyclopedic look at everything you could want to know. I deliver a worthless look at the mental equivalent of my own bellybutton lint. But the analogy is not perfect, because the kids' grandparents occasionally get a good picture, too.

Posted by Mark at 11:24 PM | TrackBack

Leaping to conclusions

Tuesday night I started seeing the darkness that comes out behind the light before you get depressed. There's a turn of mind under which whatever you perceive confirms what you suspect. I cannot think of the word for it. That turn of mind can lead you down into depression, up into mania, perhaps right into a conspiracy theory.

What is the word for that turn of mind?

A thought occurred to me then. It seemed like conspiracy theories are set up to keep us off the track of the secret organization that really controls everything. But that appeared on closer inspection to be an oversimplification. It had started to become clear I was being led to conclude a conspiracy theory of conspiracy theories by dark forces that had calculated how I would react, aiming to push me into adopting a narrow rationalist view from which the whole truth could not be glimpsed.

Manic and depressive states of mind can take on a topologically equivalent cast, the difference between coffee cups and doughnuts.

Posted by Mark at 10:53 PM | TrackBack

December 09, 2005

Every job as contracting

Forbes.com has an article about workplace covenants, whereby boss and bossed write down what they expect of each other as a way to get clear in advance about what is expect.

What would "constant improvement" look like on the boss side? Who gets to decide when it's time to renegotiate? Why the heck aren't we already doing this? (I thought we were.)

Posted by Mark at 10:20 AM | TrackBack

November 16, 2005

Why tagging is useless after the fact

When you're a writer, you have to write about something. As a reader, you must know that doesn't mean you have to read what gets written. You certainly don't have to believe what gets written.

C|Net has published an article called, "'Tagging' gives Web a human meaning." The author's smart enough to leave the question open as to whether tagging is really useful. But why even write the article?

Sure, tags can be useful if everybody at an event like baychi05 wants to pull their pictures together in one spot. In other words, it's great when people agree on something up front. It's always easier to organize things when people agree up front, isn't it?

But when you come back to search for something, you didn't know you wanted to look for it. That's what makes Google useful. It helps you find stuff no one knew at the time you were going to have to look for. And it's like a hash. No matter how much is out there, you go (almost) straight to what you wanted, even though you didn't know you wanted it until just now.

Tagging's no help there. I get to do it with my own files, my own email, my own blog entries. I still wish I could search my work files and email with Google. That's also why there are so many techie entries on this blog.

Posted by Mark at 04:59 PM | Comments (2) | TrackBack

October 20, 2005

Tech entries rebuff readers

According to Mom and Andy, the least comprehensible and therefore least interesting of entries on this blog are the tech entries dealing with computer software. (What does Bryan's mom think of dtrace?)

Of course, the tech entries are the ones I search for each time I forget how I did something. I rarely go back through my blog to browse the pictures. That's why I set up a huge page that holds them all.

Posted by Mark at 09:10 PM | Comments (4) | TrackBack

October 18, 2005

Making the right mistakes, part II

After writing up a review of Jakob Neilsen's article on blog usability, I noticed this in the summary at the top of the page:

Weblogs are often too internally focused and ignore key usability issues, making it hard for new readers to understand the site and trust the author.

First of all let me tell you as a technical writer, you must not trust the author. Never trust the author, even when the author is yourself. By its very nature, writing allows us to create mental plates of spaghetti, whose complexity can easily escape us even as we believe we remain in control. You may be sure you are too smart for that to happen. In that case, start writing software.

Weblogs are too internally focused and ignore usability issues not handled by the weblogging software, true. Most people who blog do so not because they have "vastly intelligent personal epiphanies and deep, stunning perception" (Matt's words) to share with the world, but because they feel like blogging, which they can do these days because blogging software is usable... for the blogger. The reader doesn't even enter into the consideration. If the blogger did have to consider the reader, most of us would not blog. When I think about you, Gentle Reader, it's usually because I worry that if I write down what I really think, you'll misunderstand and get upset with me. I rarely think about how usable my blog might be for you, focusing instead on the content. In fact, I don't expect you to read my blog through my blog anyway. I expect you to use an aggregator such as bloglines.com.

To new readers: "The universe is no place to start." Most of the way I understand that is in a fortune cookie I can no longer find. The author said, in essence, that progress comes not from the cutting edge, but from those things we can do without thinking about them. So Neilsen has a point there, the site needs to be so usable you simply find what you're looking for without noticing it. I don't know what you're looking for, and I sure don't know why you're looking here.

Posted by Mark at 10:51 PM | Comments (1) | TrackBack

About Mark

I'm Mark Craig, husband of Nathalie, father to Tim, Emma, and Diane, brother to Matt, who registered mcraig.org, and lets me keep web pages here. I live in Barraux, France, a town on the border between the départements of the Isère and the Savoie.

You'll still know nothin' 'bout me, but here's my CV. I work as a technical writer, writing mainly nonfiction about software.

This blog is mainly nonfiction, too. If you read it regularly, you will notice most entries seem like notes to self: running times, writeups of how I installed some software or burned a CD, recipes, links to articles, photos of the children. I'm not an inventive person; my valedictory address to the Rogers High School Class of 1988 was about continuing education. This weblog is just an external part of my memory, one that I can search easily.

Posted by Mark at 10:10 PM | Comments (1) | TrackBack

Making the right mistakes

Janetta sent me a link to Jakob Neilsen's Top Ten Design Mistakes, in which Jakob writes:

Some weblogs are really just private diaries intended only for a handful of family members and close friends. Usability guidelines generally don't apply to such sites, because the readers' prior knowledge and motivation are incomparably greater than those of third-party users. When you want to reach new readers who aren't your mother, however, usability becomes important.

This blog must qualify, therefore, for a usability waiver, right?

But I could add a picture, something about me, links to what people might want to read again (if I ever write anything like that). MovableType could make that easier than it does today, letting you add that bit when you set up a blog.

Posted by Mark at 01:52 PM | TrackBack

October 05, 2005

$66/hr.

JoAnn Hackos has published through her Center for Information-Development Management newsletter an essay on cost estimation for documentation projects. Her "typical fully burdened cost for direct employees" comes to $66/hr.

Had I been able to collect $66/hr. for the hours I worked the year I measured, I'd be a lucky guy with about $142,560. Getting me to work must be a real burden on everybody.

Indeed the development process needs to be fairly mature to have everyone contributing each of those $66 hours into the resulting documentation for the project. It does make me think of a book I once read on Open-Book management, where you show employees the accounts, giving them a clear picture of how much money is getting spent on what, with the end result in most cases being that people more easily see how to improve productivity.

Posted by Mark at 05:38 PM | TrackBack

September 15, 2005

What I understand

Reading does not seem to teach me very much. Part of the problem lies with how passively I read. It feels as though I do not do the necessary work to create a sort of dialog with the text. Should I write in the margins? Shouldn't I run out of space that way?

I have books on the shelf and on my night table where the possible margin markup could go on for a long time indeed. One on my desk right now, La Société du Spectacle, by situationist Guy Debord, has me stumped line after line. What the heck is Guy writing about? Nathalie had a look and told me the difficulty I am having does not stem from weakness in my knowledge of French.

When you have a discussion with someone, it becomes difficult to carry on when she cannot pick up on what you are putting down. Your interlocutor will hint or even state outright that you have gone beyond the limits of communication into monologue. Schooling at some point managed to get around this institutionally by permitting the teacher to blather on beyond the limit, then even assign homework to students in order to check how far they followed, which could explain why children have such a difficult time adapting to the classroom.

In writing I find it easy, even natural, to continue after I have lost the thread or no longer understand what I'm on about. If you have read the unrevised writings of others, you know what I mean. You also know what I mean if you're tried to read Guy Debord. In any case, writing may allow you to figure out exactly what you wanted to say, but it doesn't force you to do so.

Lately realizations appear independent of language. First I understand, then I may try to write down what I understand. Often I find I get lost communicating what intuitively seems fully understood. For instance, I know my way around, but have difficulty explaining how to get from one place to another. In terms of knowing my way around in fact, when I have to explain how to get somewhere, then certainly I do not know the way.

At some level the same holds true for concepts. I cannot recall understanding something in words. Yet everyone I meet with few exceptions (people who have disabilities) can translate their inner thinking into some sort of words at some level. I wonder if Chomsky had the right idea when he wrote about Universal Grammar. Would such an entity be too complicated to work with in practice?

Posted by Mark at 06:41 AM

August 25, 2005

Andy's at it again

Speaking of things better than this blog, Andy's gotten active again.

Neat pictures from Kaua'i, including a snake that looks like an earthworm.

Posted by Mark at 09:38 PM

About the tagline

Just in case I have to commit ritual suicide after my next run, I wanted to make a quick note about the tagline of this blog, so future generations won't have to puzzle it out when my brother Matt won't tell them.

It is indeed named after the Mothers of Invention cover of Directly From My Heart To You with Don "Sugar Cane" Harris on the electric violin and vocals, which came out on the album, Weasles Ripped My Flesh.

That whole album is much better than this blog. So I hardly deserve to scam on some of his intellectual property. But Frank's too dead to frown and smoke cigarettes at me about it now.

Posted by Mark at 09:17 PM

August 18, 2005

How much would you pay?

How much would you pay for software documentation?

If you're like me since about 1998, it depends. I won't pay anything at all for documentation on a software product I bought. But then I haven't bought any software, except at work, since before 1998.

I will pay money for books that teach me programming, and even system administration. But I won't pay for the man pages, for example. Even though what I use more than anything else is probably the man pages.

So I guess I want them done, but expect not to have to pay. Like system software for my PC. Of course I wouldn't want to use anything I couldn't figure out, probably with free documentation.

It becomes a tough sell when you're a cost in a world that doesn't want to pay.

Posted by Mark at 05:34 PM

August 12, 2005

Shallow diary

Technically I'm a professional writer.

As I write that, the image I get is one of God up there wiping a tear of laughter from the corner of His eye, never tiring of this long and painful slapstick comedy.

My readers are not laughing. Most are wondering why it is so long, what we used to do at work before email, and how come technical documentation got to be such an enormous haystack with most of the needles missing.

Let me remind you this is how I put food on the table.

From time to time, I hear from people who feel they might want to blog, but cannot quite get started. Some are afraid they will have to learn lots of complicated technical detail. (Not true) Others are afraid they will not have anything to say. (In that case, as Wittgenstein would advise: Take a vow of silence.)

Some worry what they have to say is not earth shattering enough. Perhaps not. Not all of us feel lack of verbal profundity is a sound reason to stop writing, since writing things down is a good way to figure out precisely what we should have been trying to say. Not only that, but also most of us start out so far from perfect that almost any practice makes better, even writing email.

Yet, okay. Let us say you have a point there, that by starting your very own online diary, you might be adding more noise than signal to the World Wide Web.

As Jean-Paul II said, "Be not afraid." The signal-to-noise ratio out on the web is so low you cannot make it worse. Google claims now to be "Searching 8,168,684,336 web pages." If you add a few thousand, no one will notice, except maybe your three friends, your mother, and God.

And He'll get another big kick out of your hubris.

Posted by Mark at 09:32 PM

August 06, 2005

Monologue vs. conversation

Ludo welcomes Michael Haines starting a blog. Tilly writes conversation starters like chats or href="http://tillybayardrichard.typepad.com/photos/concours_paris_bloguetil_/fenetre.html">this one. But it's not a French thing alone. More well known bloggers like Darren Barefoot and jwz regularly ask questions of their readers.

Wny don't I do that?

A long time ago I read a book in which this guy who'd been cryogenically frozen then resurrected in a criminal's body was selected by aliens to make a trip to the galactic center. Alone. They picked him because he didn't need much company, although he liked other people enough.

I really liked the story when I read it, and have been keeping recruitment in mind ever sense. I'm convinced this blog proves even to martians that I can keep occupied alone for long periods with very few meaningful outside stimuli. And I figure my inner ear won't get me disqualified as a space pilot, especially since the ship does all the flying.

Posted by Mark at 02:24 PM

August 04, 2005

Instant messaging and doc

One of the things I've heard said is that we read less and less when looking for information on how to do something. We search the web and scan the results. We'll read a couple of paragraphs at most. Old fashioned docs in book format can be used in that way, as long as the chunking is small enough and the writer had the presence of mind not to assume to much from chunk to chunk.

What do we do for folks who want to instant message someone for an answer? Charge by the minute, like Minitel?

What's more: What about systems for which we need basic mental models of how they work in order to get any good out of them? Training? Are we barking up the wrong tree writing down lengthy explanations designed to convey mental models? Should we give up on those treatises and write tutorials instead?

Posted by Mark at 05:25 PM

August 03, 2005

Ubuntu, part III

One of the nicest surprises with Ubuntu Linux is the Wiki. I worked my way down that page this morning, setting up what I needed in the order that it was documented. Great! Perfect level of documentation for this user.

For DSL, apparently I was looking in the wrong place, and should've seen something in the Internet submenu. That should've been taken care of at firstboot. Not sure why it wasn't.

Posted by Mark at 03:16 PM

August 02, 2005

45% die before 3 months of age

Dad sent a link to a BBC News item, One blog created 'every second'. According the the article:

Thirteen percent of all blogs that Technorati tracks are updated weekly or more, said the report, and 55% of all new bloggers are still posting three months after they started.

In other words, less than 2 million of the 14 million blogs out there are active, and 45% die before they're three months old. This blog is one of the 2 million. My paper diary is mostly empty. I type more readily than I write longhand. I spend hours everyday in front of a computer hooked up to the WWW through a browser window. Let's hope that's not typical.

Posted by Mark at 02:16 PM

July 29, 2005

Giving up truth

Until now, everything you've read in this blog has been either true or as close to it as I know how to come... or at least obviously fictional. Sometime soon I'm going to introduce partly fictional writings.

So lots of what I write will still be true. But some won't.

Posted by Mark at 08:59 PM | Comments (2)

May 06, 2005

Anniversary

It's been a year today, over 1000 entries. I saw a blurb about blogging in some junk mail Nathalie got. We must be very close now to blogging going the way of Orkut, LinkedIn, Under Construction signs, pet rocks, and hula hoops.

Posted by Mark at 09:07 AM

April 07, 2005

Independent

Carrie left me a comment, one of the three or four that come from someone I don't know, and that have nothing to do with online gambling or Viagra-like pharmaceuticals.

Carrie took a quiz. I couldn't resist, either.

6.25 %

My weblog owns 6.25 % of me.
Does your weblog own you?

Andy says he needs to do more writing and less reading. I seem to be the other way around. Tilly has the right balance. (Americans are either listening or talking. French people are capable of having conversations.)

Posted by Mark at 09:23 PM

April 04, 2005

Ideal jobs

jwz blogged Chrome Fetus comics the other day, and must've updated it, because it came up again on Bloglines.com.

Anyway, some of us have gray flannel lives revising books like the Directory Server Plug-In API Programming Guide, running a fair amount, getting home for dinner with the kids, going to bed early, having dreams forgotten first thing in the morning. Other people remember their dreams, and get dressed up for pictures like this one:

According to the page where that photo came from, Hans "has a small, but devoted following of readers and fans."

Posted by Mark at 09:35 PM

March 31, 2005

1M

It's been almost 11 months. When I export this blog, it now takes up an entire MB of disk space:

$ du -h mark.blog
1.0M    mark.blog

That doesn't count the images:

$ du -h images/
2.4M    images

Almost 3 1/2 MB. I'm so proud.

Posted by Mark at 07:21 PM

March 23, 2005

Admissions

I'm updating some old docs we converted to SGML and just noticed the following comment in an example:

/*
 * Perform other work while polling for results. This
 * doesn't do anything useful, but it could.
 */

That comment precedes a placeholder function, but you've got to wonder about the scope the original author actually had in mind. Who was it who first said, "Honesty is the best policy?"

Posted by Mark at 08:53 AM | Comments (2)

March 14, 2005

Distance

Average geographical distance between tech writers and the people whose work we write about seems to be growing faster than our ability to understand what people at a distance are up to.

If that's true, what are the implications for tech writing?

Posted by Mark at 08:57 PM

March 09, 2005

Natural anonymity

Ludo's writing about what's in Tim Bray's blog, where I notice Tim seems to have read some of the anti-blogging spin, and come to the obvious, but gracefully unstated conclusion.

In words, why go read a journalist's article about something when you can get it straight from the horse's mouth (or blog)? Especially if the horse is not some polished executive from the upper echelons but somebody like Ludo or Bryan Cantrill who has and can convey more than an academic understanding of the interesting details. The easier it gets to search and scan feeds, the harder it is for generalists to justify their positions. Pretty soon they'll have to start ghostwriting white papers for these guys and leave the news up to people who know what's really going on.

Thankfully many of us can continue in natural anonymity, churning out more entries on running that anybody but the bots will read. As Tim writes, "Blogging is a good way to meet people." If you're hankering for a conversation, that is.

Posted by Mark at 08:47 PM

March 07, 2005

Noncontroversial

Running times, training actuals, software configuration are safe topics like the weather. The further it is from the core of what you really care about, the less you have to think. The less you have to think, the easier it is to write.

Posted by Mark at 11:53 AM

March 06, 2005

Smaller pages

The cover page of this blog was getting too long. I now show only the last 7 entries, with the previous 7 entries in the Recent Entries list on the side.

This change consisted only in adjusting the main index template to use the lastn and offset attributes of the MTEntries element, so if anyone were to care, it would be easy to change back.

Posted by Mark at 09:04 AM

March 04, 2005

In vs. out

In a way it'll be cool when blogging has gone out of fashion, just because you won't see stuff like this:

La ville de Boulogne-Billancourt (Le P�le / Extrap�le) organise une journ�e enti�rement consacr�e aux blogs, qui se tiendra le 19 mars 2005.

(Source: Cyril Fiévet)

Cyril Fiévet seems to be a professional blogger at this point. I'm happy for him, but would rather be seen in public dressed up like Karl Lagerfeld than admit to being a professional blogger.

Posted by Mark at 09:27 PM

March 03, 2005

To blog or not to blog

Dad was wondering whether to start a blog. If you've gotten far enough along to wonder, I say go ahead. The worse that can happen is that you waste a little bandwidth, disk space, and time.

My brother Matt suggested maybe you should have something to say, or blog when your company pays you to. Concerning the latter, thankfully for the human race most of us do not have jobs involving primarily hot air management. Lost of Sun bloggers do it as an extension of their jobs. Few are getting paid specifically for that.

Concerning the former, you won't figure out what you have to say unless you write it down (or at least say it out loud). The good thing about writing it down in a blog is that you can erase it as fast as you come up with it. The good thing about writing it down in a potentially public place is that you will erase most of the really outrageously indefensible nonsense as fast as you come up with it.

The bad thing is that a blog is public enough that you'll censor yourself more than you probably should. But it's about as easy to drop an entry in your blog as it is to keep a journal, and it's definitely easier to search. Also there's some motivation to keep on adding entries. So it can be a good way to encourage yourself to write things down.

Posted by Mark at 08:58 PM

February 25, 2005

Schema repository, part XII

Trying to code with small children who haven't taken naps is like trying to write at work with people in and out of the office. It explains why life resembles a collection of PostIt notes, and why some people consider long distance running a relief.

Posted by Mark at 04:55 PM

February 24, 2005

Blogging down

Blogging. Why have I made this a habit? Less than keeping a journal, worse than journalism. 872K of text in the past 9 1/2 months to what end?

A blog lends itself to quick notes. I also have perhaps 700 pages of notes on meetings and ideas from work in the past several years, that and entire software manuals.

It's a great gimmick for creating a living home page, and a terrible way to think anything through. Un divertissement, like most everything else.

I'm going to be reincarnated as a pile of PostIt notes.

Posted by Mark at 08:47 PM

February 23, 2005

Priceless spam

Yesterday I received spam congratulating me for having an email address that qualified me as one of ten finalists to win 1 million euros in a lottery sponsored by Bill Gates, "To enhance and promote the use of Internet Explorer Users and microsoft-wares around the globe."

One of the reply addresses was at a free mail account. The other was... infocofidis@netscape.net.

Posted by Mark at 02:43 PM

February 15, 2005

Freedom to complain?

Another C|Net article hints you too could lose your job blogging. One legal expert observes that:

Employers have considerable leeway to discipline employees over any public expression touching on the company's business or reputation.

Lucky for people where I work, Sun tends to have people good at defining public interfaces, such as the one you need to respect when blogging. Of course everyone has been warned multiple times that it's dangerous to be caught criticizing the company in public, but the rules are easily stated. I only noted 4 don'ts.

What's interesting is less any particular company's reaction to a particular blog and more the general legal situation, how employers can discipline employees but employees cannot even make notes in their public diary (i.e. blog) about stupid things happening at work. Is that because in the aggregate companies never do anything stupid? Is it because bad news travels faster than good? Is it because our legal system is designed from the ground up to protect the powerful from the weak?

Since most of these stories are coming from the US, what about the first amendment to the US Constitution?

Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof; or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the Government for a redress of grievances.

Freedom of speech is of course open to interpretation, since my freedom to mention something stupid happening at work may impinge upon the freedom of sales folk to book orders without having to handle embarrassing questions their mark turned up while Googling, or the freedom of upper management to decide to lay people off before they read about it in The Register.

On the other hand, it's a shame we cannot build up the trust needed to relax and let it all hang out. How much success have you had solving problems you refused to identify or discuss?

Posted by Mark at 08:50 PM | Comments (2)

February 12, 2005

Asynchronous debate

Computer Scientist Alan Kay claimed in a recently published ACM Queue interview that got slashdotted, "All creativity is an extended form of a joke." Kay's generalization may be debatable, but it's also not clear whether he was kidding or explaining computer software.

Depends on how you see it?

It's not clear either whether my brother Matt was serious in email today when he said his next hack will be online debate software, but it sounds like a good joke, good enough to play with. I suggested he check out Jon Bosak and Ken Clements's Parliamentary Assistant idea, but I cannot find a trace of that getting standardized. Just email, in which Jon remarks:

I still believe that this is our best hope for a realization of the deliberative process that works online, but realistically, the implementation of such a mechanism is a long way off.

He probably has the full-strength version in mind, one that works as well as somebody with experience and firm understanding of Robert's Rules of Order. Maybe Matt can put 20% of that into PHP and SQL, meeting 80% of our needs.

Posted by Mark at 06:48 PM

February 10, 2005

Honesty

Today on an internal alias at work a guy asked how to delete his blog. He decided he didn't have anything important to say. The idea has of course occurred to the rest of us, but it hasn't slowed me down yet.

Posted by Mark at 09:19 PM

January 21, 2005

Categories

Tim Bray asks, "What is everybody doing categories for?"

Dude, because they're there. In my various $HOMEs and other partitions at home and at work, I have lots of directories that I created. Often I cannot remember what the heck I was thinking when I created both Backup/ and backup/ and proceeded to fill them with partially overlapping content. I still have to look for things with locate or find and grep.

Maybe we should use each others' directory trees for something things. We already do when we share a CVS workspace or a common repository for releases, for example. But those are cases where we've gotten almost anal-retentively organized to share a public namespace. My blog is like my $HOME, which is a mess. Thank Google we have search engines.

A good thing categories do for me is get me to remember to write about something other than my current obsession.

Posted by Mark at 10:01 PM

January 15, 2005

LDAP schema repository. part IX

Now that I've generated the equivalent of our schema reference plus draft doc for a few new schema definitions we'll include in the upcoming version of Directory Server Enterprise Edition, I have a enough Java code that I forget where I put things. It's growing beyond the point where my tiny mind can hold it all at once.

Rob suggested something Ludo suggested before, which is that I spend an hour to learn an IDE like Netbeans. Rob maintains an IDE will help me be more productive. That's no doubt true. Another thing that would help is to clean up the mess, moving the data -- SGML snippets and constants -- out of the body of the code, and rationalizing where I do things. Am downloading Netbeans 4 now...

Posted by Mark at 07:39 AM

January 06, 2005

Monologueversations

Patrick Chanezon describes in his Sun external blog how:

Netscape was all about individual personality, Sun about conformance to a process. At Sun you showed your personality in emails, at netscape in web pages.

He admits you couldn't find anything at Netscape (nor can you find anything internally at Sun) without being in the know. I agree search tools can someday bridge the gap -- hint -- and that the care we put into blog entries generally surpasses the care we put into mail, so it's easier to figure out later what the context was when you read somebody else's stuff.

We still need both. Email is a conversation. Blogging is often a monologue. Do we need to make a choice between web servers and mail servers? Can we have both... plus good search engines on the intranet and the desktop (not Windows), too?

Posted by Mark at 02:49 PM

January 02, 2005

Escapisms

Call me an amateur, a dilettante, even a dabbler. I've collected four undergraduate degrees, played with music, read hundreds of books carelessly, earned computer programmer certification, have three children, and now run.

Years ago I wondered what I'd do when I grow up. Now I wonder whether I'll grow up.

A week of vacation and no writing to show for it but dozens of blog entries, and some Java code. The road has been so well paved with good intentions I can glide all the way to my destination.

Posted by Mark at 09:28 PM

December 23, 2004

Le blogue de Tilly

Just in case anyone asks for the French translation, now you know that Babel Fish is wrong.

Babel Fish is wrong anyway, translating blog as blog. Blog comes from weblog, that is oueb'logue, which is franglais for something like journal sur la toile, which doesn't exist. Read more about the phenomenon in Libé (where the author just writes "blog").

Tilly has the good judgement with her blogue to wait until she has something to say before typing. The signal-to-noise rating is therefore than you'll find here. Tilly liked Jean-Jacques Vanier's show.

Here you find echoes of Woody Allen in Annie Hall about two women at a restuarant:

"The food's terrible here."
"Yes, and such small portions!"

Posted by Mark at 08:55 PM

December 21, 2004

Intellectual property, part VIII

We did try again today. I filled out two forms on our Invention Disclosure Tool. We'll see in a couple of months whether this is better than the lottery.

Ludo was upset with me for filing without asking around to make sure I got all the potential inventors names on the applications. He's right about that. We should look around more carefully, so next time I will. We don't appear to have appropriated anyone's ideas unfairly. He seemed quite irritated with me, though. Of course, even if we had taken credit for something somebody else might have thought earlier -- and I don't think we did -- we were only doing on a tiny scale exactly what our employer is doing to us by contract on a huge scale day in and day out. The entire system of intellectual property is based on some people appropriating what essentially could not realistically exist except in common. But two wrongs don't make a right.

I cannot put my finger on what was bothering him. The thing is, Ludo usually has good reasons for what he thinks, even if you don't understand right away. So I'm likely to be missing something important.

Posted by Mark at 09:11 PM

December 13, 2004

Less as more

Sun blogger Joey Shen reflects on writing and using documentation in his blog.

Documentation is supposed to be understood instead of showing how smart the authors are.

(Or how clueless.)

Given the way we read documentation, the writer has an uphill battle making himself understood. Sometimes we read the docs before using the object of the documentation. I started Zinn and the Art of Road Bike Maintenance that way yesterday evening.

More typically, we dip into the documentation looking for the answer to a particular question, one we could not find the answer for elsewhere. In other words, we come to the documentation as a last resort and hope to find the answer quickly.

When you're asking Joey directly how something works in his software, standing next to him in his office, you don't mind at all if he starts drawing diagrams on the whiteboard, effectively telling you, "Hang on. The answer to the question you've asked won't make sense unless I tell you all this first." You don't mind because, first, it sure looks like Joey's going to answer your question in the most direct way he can, and second, you have confidence that he wouldn't do all this with you if he didn't care about answering your particular question.

Neither of those conditions holds when we're the readers, piecing together bits of documentation written by somebody who in many cases couldn't have anticipated our questions. We'd rather Google for it. At least that way we don't have to dig through many pages yet come up emptyhanded.

Some people suggest minimalist documentation as a solution. Makes you do less digging. Trouble is, the writer has to be able to anticipate what you're going to ask, which is easier said than done in the real world of complex software.

One partial engineering solution to the problem is to make things a simple as possible (though no simpler). In other words, if what you're creating can work without documentation, do it that way. We might even extend that to say that if what you're creating would be easier for almost all users if it didn't require reading the docs, go ahead and slightly frustrate the 5% of users that really want tweakability. Or make the default behavior something that works for 95%, even if it makes things slightly harder to tweak for the other 5%.

Posted by Mark at 05:53 PM

November 17, 2004

Hard to read

Buckminster Fuller writes in an author's note for Synergetics that you need to go over and over almost the same ground in order finally to understand.

Friedrich Nietzsche explained in the preface to Genealogie der Moral that you'd better be a cow than a man to appreciate his work and in any case not a "modern person." Digesting his work requires "Wiederkäuen," rumination.

Ludwig Wittgenstein tells us right away in the preface to his Tractatus Logico-Philosophicus, "This book will perhaps only be understood by those who have themselves already thought the thoughts which are expressed in it--or similar thoughts. It is therefore not a text-book."

Jesus's observation that "everything comes in parables" seems to stem from the same vein of warnings to the reader, warnings that it's not going to be easy.

Yet I get the impression these four men slaved to make their words as straightforward as they could, that they did what Kurt Vonnegut says is so hard, which is the work of making things simple for the reader. It must've been hard indeed when they started out.

Posted by Mark at 09:33 PM

November 16, 2004

Wolves and other stories, part II

Just in case I didn't make myself clear, the previous entry is not supposed to make sense.

It functions only as a counterexample to Luke's flippant assertion that we think in words, even though he shares an office with Rob.

Posted by Mark at 08:56 PM

Wolves and other stories

Over coffee this morning I failed to explain myself. This happens to me all the time. I do not think in words, but in something related to metaphors.

Karine explained that one of her children -- I think it was Thomas -- had been told a story about a wolf or wolves at school. When he came home he couldn't sleep before his parents opened all the closets and cupboards to show him no wolves were hiding in the house. Karine's husband David asked the teacher why they'd told the story about the wolves. The teacher responded children need to confront their fears, and they do that through these stories.

Gilles concluded that was true, that children need to confront their fears, or they remain too afraid to try anything.

Before he said that, I tripped over my words. But I saw what I later wrote down, an explanation Occam might have cut to shreds. In essence, Gilles's explanation is the surface explanation, put there to protect the hidden story from discovery, which is that somebody at l'Education Nationale was taking aim at the church, intentionally helping children build their superegos from flimsy fears of wolves and other unlikey happenings. The unconscious would respond to these fears; the children would first appear to become socialized. Other stories about scarcity, unemployment, etc. would round out the superego scaffolding.

But in the end, the ego would notice the flimsy core materials of the scaffolding, would put two and two together to deconstruct the superego, which would vanish once exposed. The ego would see the unconscious confused by the boundaries of the flimsy, fake superego, and begin the work of taming blind, unconscious drive. No God above, no demons below, only rationality remains.

Yet behind the hidden story hides another short story. Rationality is only a tool. It constructs nothing on its own, but disintegrates into its own relativism, and thus anarchy. In the absence of structure, the ego makes no sense, so it must disappear as well.

Thus at one level, the story about wolves is an object lesson in Zen Buddhism. I'm still looking for the hidden story behind Zen.

Posted by Mark at 08:52 PM

November 08, 2004

Situation appraisal

Following the training in problem solving last week, I started a situation appraisal. I identified 8 top priority concerns, three of which relate to my job. Of the others, two look to my future. Three center on relationships with other people.

Of the three that relate to my job, I can probably resolve two through email. That leaves one more, and it's at the core of what I'm supposed to be doing at work right now anyway.

The other five may take longer to resolve. All of them look hard to handle well. So why focus on work? Procrastination may explain more than I thought.

Work for which I'm paid seems serious, important. Responsible people encourage me to view it that way. I even encourage myself to view it that way.

Posted by Mark at 10:03 AM

November 05, 2004

Weather conversation

Writing about the running and cycling I do is like talking about the weather. It's safe, easy to come up with something to say, and almost utterly devoid of interest.

It could be worse: I could be blogging for dollars.

On the other hand, it could be a lot better. I think I'll start a journal as well, which you'll never see, but which may someday generate something worth reading.

Posted by Mark at 09:24 PM

November 04, 2004

What you cannot say

A blog is not a journal. As soon as you know you're not the only one looking at it, you exercise censorship.

Posted by Mark at 07:00 PM

November 03, 2004

Comment spam, part V

Following yet another rash of comment spam, this one quite distasteful, I've decided to start closing comments for old entries, using mt-close.cgi, which I downloaded from David Raynes's site.

If you want to leave a comment on an old entry and cannot, let me know by email.

Posted by Mark at 08:57 PM

Comment spam, part IV

Yet another rash of comment spam.

This is getting to be a pain. MovableType's comment management doesn't seem to permit easy bulk deletion.

Posted by Mark at 07:41 AM

October 29, 2004

Comment spam, part III

Got hit with another rash of comment spam. It's almost enough to make one want to turn off comments.

Posted by Mark at 07:05 PM

October 24, 2004

Scrapbook

Fuller wrote he kept a scrapbook, though he didn't call it that. Drucker claims the executive must review the written record to identify his strengths and weaknesses, to find out who he really is. Drucker and Fuller see writing as contracts with themselves; the salient achievements of a man's life he records in contracts (with himself). This ensures his progression, and permits analysis then correction of failures to progress.

A man's life must resemble history, not literature. A man's life has nothing romantic to offer. His story is not a story, just a history.

Good history and literature do not betray their origins, which are in revision. The unexamined life is not worth living. The unexamined blog not worth writing.

It is only numerically true that in the infinite library, all books exist, and so must the supreme book. In reality, all of us wander endlessly through hexagons of gibberish.

Posted by Mark at 11:33 AM

October 22, 2004

Personas

Steve Calde wrote an article on Using Personas to Create User Documentation that I read about in somebody's blog.

When I went to read the article, I saw it started off:

This article assumes that you already have a set of good user personas, presumably based on good design research performed as part of the product development process.

Steve, could you give me a real example of software:

• That really does require documenting, because the user interface cannot be intuitive enough to avoid documentation
• For which the prerequisite design research has been done

Such software must exist, but no examples spring to mind.

Posted by Mark at 09:26 AM

October 06, 2004

1 in 6

This blog includes about 1 image for every 6 entries. Since entries with images often include more than one image, images are few and far between. Definitely fewer and father between than the Dilbert feed at Tapestry, which is also more entertaining than this blog.

You can view all the images I've uploaded in alphabetic order at http://mcraig.org/mark/images/ (712 KB).

Posted by Mark at 09:03 PM

September 22, 2004

Whois

Some oddness looking at the statistics for this site:

• 15.12% of the hits are coming from an IP address registered to Microsoft Corp.
• 9.72% of the hits are coming from another IP address registered to Microsoft Corp.
• 2.73% of coming from some nameserver registered to a company in Poland
• 27 hits came from a server in navy.mil

Why is Microsoft generating 25% of the traffic on our site? Maybe you'll find a bunch of banner ads for Microsoft products in old blog entries I haven't read in a while.

What tripped off those .mil servers? Maybe I accidentally did something to jeopardize Sun's export clearance and will soon be tried for treason and failure to protect national security. (Already searched my blog for "terrorist." No hits were found. Until now.)

Posted by Mark at 10:24 PM

1 subscriber

Bloglines.com says I have 1 subscriber. Namely myself.

I don't of course read my blog through bloglines.com. But it lets me check that the feed works.

Not sure why I do that. Maybe I should start recording myself talking to myself as well, just to make sure I'm mumbling clearly.

Posted by Mark at 09:42 PM

August 14, 2004

Comment spam

This blog, as anonymous as it is, gets hit with spam comments every other day or so.

Today brought a bumper crop of Viagra advertisements, however. Maybe you'll never know about that cheap, special low price offer ;-)

Posted by Mark at 08:51 PM

August 06, 2004

Spelling mistakes

I must shamefacedly admit my capacity to spell correctly laisse à désirer both in French and in English.

Dana pointed out one mistake in No breaks, breaks for brakes, demonstrating my ineptitude handling even the lowest form of humor.

Humorlessness looks okay (OK?, O.K.?) to me. Inability to spell does not. I earn a living attempting to write non-fiction.

Life eventually wears down hubris, demonstrating total incompetence until you admit it through your tears and both of you look at your shoes. Too bad Larry Wall's right -- "The three chief virtues of a programmer are: Laziness, Impatience and Hubris." We need hubris to get something done.

Posted by Mark at 08:16 AM

July 24, 2004

Holding out for Java ES.next

When Matt Swift came to work with us, he was looking for the quick start guide to using Directory Server. He's right, we ought to have one of those. Our current docs are written for folks deploying large-scale directory services. We're missing a tiny quick start version for hackers.

Since I reinstalled Red Hat 9 at home, I was hoping that the Directory Server from the latest version of Java ES would run there. But alas, Red Hat Enterprise Linux 2.1 appears incompatible with Red Hat 9 to the extent that it doesn't really work. Maybe it'll be closer if we support a more recent version of RHEL in a future update of Java ES. Holding out on the quick start until then.

Posted by Mark at 03:50 PM

July 20, 2004

Better than release notes

In trying to get my VPN working -- so I can work part of my 35-hour week at home when I cannot be in the office -- I ran across some exciting reading at Cisco. It's even better than our docs. Hundreds of lines of "good" log output.

You scroll for what seems like forever to get to a section entitled What Can Go Wrong. Of course nothing in there helps. Could be the wrong version?

Posted by Mark at 10:13 PM

July 16, 2004

Examples: doc or code?

Netscape used to consider sample code part of the documentation:

Whether describing how to create hierarchies of objects in JavaScript or offering sample code to copy and paste, DevEdge Online documentation includes a variety of references to guide and assist development using Netscape products and technologies.

When reading with a developer or sys admin hat on, I certainly see sample code as belonging to the documentation. Why ask the question, then?

• We deliver sample code with the bits, not with the docs.
  In other words, you may be able to copy code directly from the HTML version of the docs, but it's rarely as easy as it ought to be.
• Sample code sometimes looks like somebody wrote and formatted it as the last little task to complete before sending a status report and leaving for a long weekend.
• Documentation and examples get out of sync.
  That's like your right hand getting out of sync with your left.
• Most "documentation" tools and formats force you to do some processing in order to include source code even from common languages verbatim

Yet another ease of use problem. What's a good fix?

Posted by Mark at 10:04 AM

July 13, 2004

Rathole (verb)

Dennis used rathole as a verb today. I'm not sure whether it's one word or two.

rathole (verb)

To enter a restricted discussion space from which it is hard to return to the larger discussion; Example: "The Working Group Review Board has no charter or rules of governance. We just rathole on one random topic after another until it's time for lunch."

Posted by Mark at 07:13 PM

Don't let kids think

Jamie Zawinski wrote about ClearChannel rejecting an anti-war ad. The folks interviewed play squarely into Herman and Chomsky's propaganda model:

"Never has anyone said to me from Clear Channel corporate that I should or should not put up copy because of its political ramifications,'' Meyer said. "That's contrary to the principles of the company -- we're in the business of maximizing profits for our shareholders.

Meyer said ... [ClearChannel] generally does not run copy that would be unsuitable for children or cause them to ask difficult questions...

Quotes from an SFGate.com article, Bay Area group in flap over anti-war billboard.

Liberty seems like too much work. Let's just go back to believing what we're told.

Posted by Mark at 09:34 AM

July 11, 2004

Random premises

Ellen Isaacs and Alan Walendowski wrote Designing From Both Sides of the Screen, which I'm reading to counterbalance a book Stu lent me called The Corrections by Jonathan Franzen. Franzen seems first to have contacted, then to have dated, and finally to have moved in with the same muse that tortures Luke's nightmares, descendant from hr�nir of whatever killed the Elder Race, and whose telepathic control beyond time caused the Thule Society to look mistakely to the North, leading them away from Lovecraft's Antarctic Atlantis. (Barjavel found it, too.)

Ellen and Alan start with the premise that you "Understand users' needs." That sent me back to Jonathan, where Chip with salmon melting in his pants listened to Doug considering purchase of an alternate personality, even to our Jonathan and his robots. Jonathan, stubble rather than ponytail, engendered embarrassment which led me, as though holding in a sneeze, to refrain from seeing Ellen and Alan's reverse-brainstorming-envisioned starting point as Antithesis before yet another synthetic, foreshortened, vignette Chomskyesque pre-cognizant, early-morning flash critique of the Entire System (aka Black Iron Prison) under which the lure of stock options and the weight of our furniture prevent nearly all of us from true software development.

Logicians say that "From False Premises Come False Conclusions." The statement implies a belief in effect from cause, in the possibility of tying the two together through logical argument.

The best we could do under the circumstances of the second law of thermodynamics coincided with delivery of 3000 pages in words and pictures, with artifacts such as nsslapd-autosize-cache: "This performance tuning related attribute is turned off by default. It specifies the percentage of free memory to use for all the combined caches." Users of course have issues, needs, and concerns of their own, just like Iraqi children.

To abuse the is of identity: The universe is not malicious. It's random.

Posted by Mark at 09:15 AM

Hr�nir

In Tl�n, Uqbar and Orbis Tertius [ES] Borges describes archeologists' use of hr�nir, secondary objects multiplied from lost originals, to augment and improve the past.

Google returns no definition, yet. The Wikipedia article seems painfully premier degre, although admittedly Rome wasn't built on Internet time. Of the languages invented for the Web, perhaps only Perl would allow you to say something like, "Upa tras perfluyue lun�." (Upward, behind the onstreaming it mooned.)

"Occasionally a few birds, a horse perhaps, have saved the ruins of an amphitheater," so imagine in what dilapidated state this blog maintains... what?

MovableType has an enticing little utility down the left-hand edge of this browser page:

By sheer force of will, and hours of editing, could one polish this into something more archetypical?

Hr�nir like Lovecraft's Necronomicon (recursive hr�nir?), Eckel's Thinking in Java, even ordinary novels preserve interesting shadows of the ideal. But could one through carefully maintained hr�nir preserve the dull, everyday Brownian boredom of our lives? Through painstaking editing, discipline, and unyielding regimen of creation preserve the second law of thermodynamics itself?

Posted by Mark at 07:28 AM

July 09, 2004

Why tech writers don't categorize like readers

Vesa Purho suggests in Documentation or Training? � Boundaries Get Blurred that readers shouldn't have to decide whether they're looking for documentation or for training. Sounds good. From personal experience, I'd throw troubleshooting, aka support, in there as well.

And we therefore put the boundaries back in for the same reason programmers came up with scripting languages, object-oriented programming languages, and tag libraries. The writers couldn't handle it.

Good documentation fills the gaps between what you're trying to do with the thing you're reading about, and what its exposed parts seem to let you do. But the exposed parts, sometimes known as the user interface, depend intimately on you, more than on the subject of the documentation.

For example, using a washing machine to clean laundry exposes parts that you model with abstractions like water temperature, spin speed, trays for detergent and fabric softener, start buttons, etc. Reparing a washing machine exposes belt drives, rotating drums, internal plumbing, etc. You can almost keep the distinctions clean there. Washing machines expose two nearly distinct user interfaces. Most writers, given a bit of understanding about washing machines, could information map out not only how you use a washing machine, but also how you troubleshoot it, and therefore everything you as a reader need to learn about it, unless you're the one doing R&D in washing machines.

Categorization gets murkier when you look at troubleshooting software. Interestingly, and although we writers try to pretend it's not so, the only time most of us return to documentation after we install software is to troubleshoot. Online training? Maybe it's taking off economically because it's subsidized by companies who somehow got sold on the idea as a cost-cutter. My experiences with online training have been uniformly disasterous. Troubleshooting with help from Google? Now there's something real.

But troubleshooting real software feels hard to do, let alone to understand enought to write about. What do you write when you realize that this blog entry is already far longer than anyone is willing to read, and yet even explaining the background needed to understand what can go wrong with multi-master directory server replication takes much more? You try to find good examples and hope they'll fit. (Another reason to expose you're *-interest mailing lists to Google.)

Hard work, even for an expert. Writers who try it may come back with just a FAQ and a bunch of good intentions, maybe a reference in Related Reading to Zen And The Art of Motorcycle Maintenance. So we categorize like writers, because we end up with writing we can do.

This is turning into an apology for Bryan Cantrill's 368 p., 1.3 MB DTrace guide, written by Solaris kernel hackers rather than somebody with a tech writer job title... Or the GNU make doc. If you want something written just for you, write it yourself.

The beta version of the DTrace doc incidentally has no occurrences of "trouble" according to Acrobat Reader.

Posted by Mark at 07:47 AM

July 02, 2004

Uproar over... docs

The running joke is that nobody ever reads the docs. It's not quite totally true.

After Richard Elling reported Sun BluePrints were going due to budget cuts, people came out of the woodwork to complain. The blog entry got cited even in The Register, now running a story about how the decision got overturned.

Posted by Mark at 10:36 PM

June 25, 2004

Open to freak ideas?

It occurred to me early this morning, the time of day when dreaming or whatever has resolved most of the contradictions that bubble up slowly, and I can see all the motes in my brothers' eyes very clearly.

I tried in the past to get Rob to read Robert Anton Wilson. He was steering me back to Russell and Penrose, but I'm both lazy and flaky, so it's like pushing a cooked noodle. But I got Rob to start Critical Path, warning him about the style, but not about something I'd missed, the part that must be in there somewhere in which Bucky concludes that dolphins evolved from humans or the other way around.

This almost got Rob to put the book down. In fact, I'm not sure he's not just hanging onto it out of good manners.

Arguably, Critical Path contains a lot more new information than Understanding Power. Noam's dragging us through the crap that we wade through, dogmatically holding our indoctrinated noses. Bucky's pointing to infinity and reminding us to leave the planet, showing us nature's path tangential to that of the mainstream thinking primate.

Noam even tells us why Rob can read Noam, but not Bucky. If you come up with something outside the mainstream, the proof required increases enormously. Noam knows this; he does it. Bucky doesn't seem to want to spend that much time on it.

So Bucky trots out some mixed primate and dolphin evolution, and that really puts us off. But when Noam in Understanding Power gets off track into some discussion about why if tabacco is legal, why shouldn't marijuana be -- Dude, you can smoke a whole pack of cigarettes and still drive competently, and most adults in the US are constantly in and out of cars, operating insanely complicated machinery like PCs just to get their jobs done, etc., serving those in charge -- and we just sort of gloss over that and get to the next section.

The logical conclusion to rejection of Bucky would involve ignoring everything that has such blips (this blog, lunch converstations, all of TV, your mom, most publications including Noam's, etc.). You confine your reading to logbooks from scientists, mathematical textbooks, and maybe some crap that's so complicated you cannot tell whether it's wrong or right, like Wittgenstein's Tractatus.

I have yet to meet someone disciplined enough for that. Let your freak flag fly.

Posted by Mark at 10:13 AM

8+ levels of hierarchy

Martin Hardee wrote about Tufte's original comment on AnswerBook (before the web version). Tufte's quoted as remarking:

Dr Spock's Baby Care is a best-selling owner's manual for the most complicated 'product' imaginable -- and it only has two levels of headings. You people have 8 levels of hierarchy and I haven't even stopped counting yet. No wonder you think it's complicated.

IMHO, Tufte misjudged there. Babies come without history. As a parent, you know how to operate them almost intuitively.

The same is not at all true of UNIX.

Posted by Mark at 09:40 AM

June 24, 2004

Why the manual sucks

In Understanding Power -- yes, I'm enjoying this one -- somebody asks Noam a question about why people in the US are "anti-intellectual." They discuss terms for a while, finding differences between "intellectual" celebrity and real intellectual work. Norm seems to come down on the side of real intellectual problem solving work, observing that a lot of what passes for "intellectual" work (leading to notariety in places that are not "anti-intellectual" such as France) strongly resembles clerical work you can do with considerably less effort than problem solving.

So then, Noam's questioner says, "But people do look down on people who read books."

And Noam answers, thinking of an imaginary, highly capable auto mechanic solving tough car problems, "But look, this guy may have read books--maybe he read the manual. Those manuals are not so easy to read; in fact, they're harder to read than most scholarly manuals, I think."

Writing software manuals (and their cavalierly misnamed cohorts called guides because they include procedures) being what I do for a living, I have some guesses as to why they're so hard to read.

Typically, you read the manual for hints on solving the problem at hand. The writer wrote the manual without knowing what problems you were going to encounter. The writer probably worked on it with the builders, rather than the users like you. The writer probably had to finish the manual, moving on to the next version or even a different manual both before you got the product it covers, and before learning enough to function as a real user. After publication, the manual content remained unchanged. If you're lucky, someone published errata (usually written on hearsay).

Futhermore, you come to read the manual with all the particular background knowledge that makes up your understanding of the situation, and probably with a number of preconceptions that, if exposed and reconsidered, would help you avoid getting stuck while solving the problem. The writer comes to write the manual with a totally different set of knowledge and expectations, probably without much background in the subject, most people who have background working as builders rather than writers since building has significantly higher status and probably higher pay, and vitually no knowledge of your knowledge.

So the writer may write straight exposition on an inadequately understood subject, whereas you are suffering through a complex problem solving situation, or are reading with the intention of solving problems. You experience that as the manual sucking.

Authors of scholarly works, on the other hand, typically have become experts on the subject matter, are writing for folks taking the same path toward expertise, and don't expect you to approach their work with the intention of solving problems. You experience this as the scholarly work being easier to read.

Posted by Mark at 04:33 PM

June 22, 2004

Summertime

It's now summertime in the northern hemisphere.

Do you know how your reindeer are taking it?

Posted by Mark at 10:20 PM

June 21, 2004

100th entry

100 entries in this blog in a little over a month. I'd never have done it if it had to be on paper.

Now if only it were as easy to log tidbits of video.

Posted by Mark at 05:28 PM

Back to developer doc

After having led the doc team for a couple of releases working on installation and reference stuff with only a little bit of plug-in development doc thrown in for good measure, I finally get back to the fun stuff. This time it's for directory client SDKs that originated at Netscape. One for Java code, the other for C. Wish I could concentrate on that exclusively.

Sun's also doing more complete solutions for identity management than ever before, including Directory Server Enterprise Edition at the data layer. So a big part of each week goes to making the docs for that even more complete. I can see the next big peak we need to reach in that area: how to say even more in 2/3 fewer words and pictures...

Posted by Mark at 05:26 PM

June 16, 2004

Careful what you write

Halina Tabacek got invited to the latest McNealy Report radio show. She said:

You have to be careful what you write because somebody might actually read it.

On the one hand, not sure what that means for blogs. This blog's been Google'd by now, but I doubt from the webalizer output that anybody else is reading this.

On the other hand, when you put something in documentation, especially tucked away in the reference, somebody somehow gets in there and reads it. You'll get readers coming back wondering why they cannot increase nsslapd-db-logbuf-size without rebuilding all the databases. (I now realize I cannot remember what the answer is.)

Posted by Mark at 08:51 AM

June 12, 2004

Autobiography of a loser

Back when I used to think I might want to write a book to read, rather than consult, I realized all of Borges ideas for books lie beyond my lazy reach, Dick has a better mind, and non-fiction would involve the kind of deep research that produces a Pavlovian procrastination reaction.

One remaining idea I summed up as "autobiography of a loser." A self-absorbed, embarrassing-even-while-auto-derisive protagonist, saved only by your feelings of superiority. Then I realized it would have to be humorous, and decided to go to bed.

Posted by Mark at 09:25 PM