Tag Archives: writing

Blogging, and feedreaders

2 Comments

A week or two ago I had a conversation with Stormy about the lost art of blogging, and blog reading. Long ago, Google Reader was a daily routine, and kept me in touch with the blogs that I wanted to read, and made me more likely to write blogs of my own. When Google Reader died, nothing really took its place, and the thing that kinda sorta took its place – Facebook and Twitter – do a terrible, terrible job of giving me the sources I actually want, and, instead, feed me a steady diet of pablum and clickbait.

Yesterday, Anil Dash tweeted about Google Reader, and made some great observations about what an important tool it was for a certain population.

The entire Twitter thread is worth reading … and would have made a good blog post.

These two things have inspired me to try Feedly again. It is much better than the last time I tried to use it, and I have high hopes that I’ll actually stick with it this time, and make it part of my daily routine again. I hope. I also hope that this will result in my actually writing again, like I used to do, on a nearly daily basis.

Writing

I’m reading ‘bird by bird’, by Anne Lamott. It’s one of those annoying ‘how to write’ books that assume that you have the luxury to quit your paying job and write full time. It’s a recipe for frustration. Yes, I want to write full time, but I have to pay the bills, too. And I want to work on the Apache HTTPd docs. And I have some things I want to do with the PHP docs. And I need to rewrite my mod_rewrite book. And I need to finish building a bookcase, and learn how to cook gumbo and record the rest of ‘Jungle Book’ and … before you know it’s time to go to bed and get up and get the kids off to school.

Anyways, this book … it’s full of marvelous advice that has already made me want to spend hours and hours writing, which is, as far as I can tell, the central message or the book: Just sit down and write, and don’t worry too much about it. Get into the habit of writing, and don’t be afraid to write terrible stuff, because if you write enough terrible stuff eventually you might write something good.

Highly recommended.

Write a better FM

I’ve been delighted to see the “Write a better FM” meme that’s been spreading slowly through various blogs. I understand that I’m to attribute this to Kathy, but I’ve been saying this for years. It’s not sufficient to tell people to Read The Fine Manual, you have to actually listen to the questions that they are asking, and make sure that TFM actually answers them. And, if it doesn’t, then make it better.

This is sometimes as easy as it sounds, but usually isn’t, for reasons that are often non-obvious to people that are in a place to make the world better.

It’s too hard to make the docs better. Those of us who are involved in documentation need to:

  • make it easier for folks to tell us what’s broken
  • be less defensive when they suggest ways to fix it
  • clearly identify our audience and listen to their problems
  • provide clear, correct, efficient ways for them to achieve their goals, rather than telling them that they have the wrong goals

If we don’t, what happens is that a thousand stinkweeds bloom. I’m discovering this the hard way with mod_rewrite. Because the documentation for mod_rewrite is so intimidating, and folks don’t know how to contribute changes to it, instead they write hundreds of HowTos and tutorials and recipes and rants about how to do things in mod_rewrite. These articles are, for the most part, wrong. The ones that work, often do so by sheer chance, and are prone to break if attempted elsewhere. But desperate users take these tutorials, hack on them until they mostly work, and they pass their hard-won ignorance on to other folks.

We could have prevented this, but we chose, by our inaction, not to do so. The problem is *much* harder to fix than it would have been to prevent.

I’m thinking about better ways to allow end-users to tell us that the docs suck, or to suggest improvements. I’ve never been a fan of the PHP methodology, which I have at times called “Scripture With Commentary”, primarily because so much of the commentary is crap. However, it gets the job done, and seems to be the best of the bad. I’d love to hear your suggestions of better ways to collect user feedback, and, perhaps more importantly, incorporate it into the end product.

Writing Documentation

Someone (and I now can’t remember who – I think it was Philip Olson) pointed me to Writing Open Source this week, and I’ve been somewhat fixated on it since.

I’ve been writing technical documentation for more than a decade now. 12 years sounds about right. Let’s go with that. I’ve been told I’m good at it, so I keep doing it.

I’ll let you in on a little secret. I don’t tell just anybody this, because they think I’m a freak. I actually enjoy writing documentation. I enjoy figuring out how things work, and then writing about it so that other people don’t have to figure it out. I enjoy catching the first glimmer of the spark of understanding when someone reads what I wrote and gets it for the first time. I love it when people say “Oh! I didn’t realize it was that easy!” and “Why did it seem so complicated before?”

There are precious few places that do documentation well. There’s a number of places where Open Source documentation, and software support in general, typically falls down.

* Tell the user that they’re an idiot, and probably too dumb to use this software. This is done in a variety of ways, and is often abbreviated RTFM, but TFM is often insufficient.
* Pretend that the end-user cares about the architecture of your software. They don’t. They just want to get their job done.
* Fails to distinguish between end-user and developer documentation, and, if there is a distinction, the path from one to the other is left as an exercise to the reader
* Refuses to consider the interrelationship with related technologies, and continually tells the user that “that’s a problem with ProductB” rather than giving them the support that we’re qualified to give.

And many, many others.

As I looked at this website, I became more and more persuaded that perhaps I could help in the effort to write a guide of how to write Open Source documentation – not from the perspective of whether to use passive voice or not, but from the perspective of identifying with your audience and answering the questions that they’re actually asking, not the ones that you feel that they should be asking.

On a related note, during a recent conversation on IRC I suddenly realized that I’ve been working programming jobs all these years because I haven’t been able to find a position that’ll pay me to do what I really love – writing technical docs. I wonder where this realization will take me in coming years.

Sestinas and writer’s block

A sestina is a poetic form. It consists of six-line stanzas, with each stanza’s lines ending in the same six words, in a different order for each stanza. Then there is a final stanza, called the envoi, in which each line contains two of the six words.

You can see examples of sestinas here, or provide your own six words to see what form comes out.

It is incredibly hard to write a sestina that doesn’t sound forced, and hardly anybody ever manages it. A really good sestina, when read aloud, is not immediately identifiable as a sestina. It just sounds like there’s a rhythm in there, but you can’t quite place it until you read it that third or fourth time, and see it on a page.

Most sestinas, however, work for the first stanza, and possibly the second, but after that you feel that the author is just saying any old nonsense just to stay in the form.

Sestinas work best when they are about a repetitive topic. Examples might be a child’s game, or an addiction, or a daily event. So I thought that the latest topic on Inspire Me Thursday – Breath – would be ideal for it. Unfortunately, so far, it just sounds like, after the first stanza, I’m merely babbling to fit the form.

I’ve had a really hard time writing lately. Everything feels forced, both fiction, poetry, and nonfiction. I keep hoping that if I force it long enough, it’ll start to flow. But the pump refuses to be primed.

Writing a book

I’ve been looking for a decent tool with which to write a book, and haven’t haven’t had much luck.

Pages is nice for laying out stuff, but although it does a Table of Contents nicely, it doesn’t do indexing. I’ve been told that there are templates that do indexing, but I haven’t had any luck in finding them.

Word does indexing, of course, but it’s so amazingly difficult to add an index term that it actively discourages one to do it.

The process, by the way, is:
* Highlight term
* Click on “Insert” -> “Indexes and tables”
* Click “Mark Entry”
* Fill in the term that you wish to appear in the index.
* Click “Mark”
* Click “Close”

Simply having a shortcut key to highlight and mark, or perhaps highlight, right-click, and mark, would greatly increase the effectiveness of this process. If I don’t index while I write, I don’t index.

I could use DocBook, and probably will, but the tools for converting DocBook to anything else are SO geek-centric that I find them profoundly tiresome to use. Having to spend an entire day researching and installing and configuring in order to write content seems excessive.

And of course, I could go back to writing LaTeX. Once I get back into the swing of it, I imagine that it would be the most efficient thing to do. But the output tends to be a little on the sterile side, and it’s hard to do specific layout like image flow, sidebars, and so on – although I’m sure that a dozen people will respond and say, it’s really easy, you just follow this 12-page HowTo. Oy.

Anyways, if someone can simply point me to a Pages template, that would of course be the best of all options.

For the most part, though, it’s frustrating that one either has to be an uber-geek in order to use any of the readily-available book authoring tools, or spend a lot of money on some other tool.