Skip to main content

A Developer's Life: Honing Your Writing

Developers hate documentation.

I don't write that as anything but a statement of fact. Documentation, once an idea has been put on paper or in writing, is instantly out of date. And if it's out of date, what's the point?

In fact, sometimes I think the only people who like documentation are those who:
a) are paid to write it (technical writers)
b) paid to prove it exists (legal) or
c) paid to show some form of output for a failed effort (managers)

Even online documentation is out of date. Going to the MSDN site for virtually any product now has a "Applies to version" because the functionality changes regularly and even then, you will always find an article that was written once as an example of how to do something right, that has been commented on to the point of how not to do something.

But now even worse, you find a link or a post you like. At the time, you wanted to quote it, maybe even copy it, but attribution should be enough with a link, right? But when you want to go back to it years later, it's gone, replaced by a lovely 404 message. (this is one of the reasons I LOVE that many FoxPro developers put their earlier papers online for easier access - some may be out of date but they are there)

Even with proper links, you have to find the date it was originally written. Sadly some writers or posts don't even bother with a date, leaving you to guess.

Thus, consider the popularity of the Wiki (wikis.com may have been for sale for years, but fox.wikis.com was updated on the 22nd of February - THANK YOU Steven Black.). Documentation that can be modified, rightly or wrongly, on an ongoing basis. It's updated, sometimes in small tidbits or in large swaths, carried out, no doubt, by those living at home with their parents in their pyjamas at night. I can say that, as I originally wrote the draft for this at 5am.

But even Wiki articles can be out of date. One of my clients, Government of Canada, have some great initiatives including their own internal wiki (GCPedia) (inaccessible outside the government network). But many of the articles are out of date. Google it and you'll see that many of the first page articles are from 6 years ago. As with many initiatives, the early enthusiasm gives way to ennui.

With one of our recent projects, which uses the GCPedia as its host for documentation, keeping it up to date is a constant activity. In a recent internal poll, one of the comments by our own developers was how out of date it was.

Everyone wants their work to be "evergreen", that term for pieces of work that stand the test of time. But is there ever such a piece of writing? I have a copy of "Outline of History" by HG Wells (two volumes). Originally written in 1920, you can only imagine how much presented in there was either a) outdated by the time it was printed or b) just plain wrong.

(as an aside, I often think about how NOT evergreen many podcasts are, including the FoxShow, which almost makes them just like bad writing. So while I haven't stopped producing shows, I'm trying to find ways to make them closer to evergreen)

This isn't to disparage those who write. In fact, it's meant to inspire. Why?

Coaches, mentors, spiritual leaders all lead their pupils in spoken mantras. This helps embolden, enthuse and even solidify their efforts. When someone wants to accomplish something, even just the act of saying it out loud makes a difference.

But just as much, putting pen to paper, or fingers to keyboard, or mouth to microphone, also serves a similar purpose. It solidifies a concept, even if it goes out of date the very next second. It forces you to THINK beyond just an idea.

I once (circa 1990) had an idea for a handheld device that would record a voice message and then send it on the network to another recipient, translating the voice to text (as much as that was possible back in 1990). It didn't need a keyboard because that would be in the way, although it did need buttons but the most important aspect was this communication piece. Sure, there were cell phones back then, but this would have been a device I would really like. I thought it was ingenious --- I even drew up a prototype and put an Apple logo on it, because after all, I was a person who bled in six colors and only they would be able to make such a device (ah! the naivety of youth). But I didn't take it further. I didn't think about the other aspects about it. My mistake.


Writing helps you think about the audience and fleshes out the concept, especially when you focus on ideas. It takes you down the rabbit hole and if you ever get to the point of being able to write streams of consciousness, helps you not lose any of those ideas. Coming back to older writing also helps you ensure you got the point across correctly.

I haven't posted in a while but I've been writing. I currently use 750 Words as my "sounding" board. It helps me solidify ideas but with some added bonuses. I also try to write 10 ideas a day, although I will say that the Idea Machine book hasn't really helped me about.

We have a book at home called More Political Babble and one of the parts that always makes me chuckle is a piece about  Newt Gingrich:

"When Gingrich was speaker of the House, Bob Dole was the Senate majority leader. And so Dole spent a lot of time listening to the speaker’s proposals. “Gingrich’s staff has these five file cabinets, four big ones and this little tiny one,” he told The New York Times. “Number one is ‘Newt’s ideas.’ Number two, ‘Newt’s ideas.’ Number three, number four, ‘Newt’s ideas.’ The little one is ‘Newt’s Good Ideas.’”" 

I take an idea and then try to see how it can be built. By writing about it :

a) how could I tell someone about it so they understand?
b) how can I write it so that it's actually feasible?
c) how can I ensure that it's deliverable?

By writing these items out, I improve, not just my writing, but also my ability to deliver on my ideas. Delivery isn't always about shipping a product - it can be about changing a point of view, shaping an hypothesis or validating an argument. In software development, all of those skills are needed.

So yes, I realize that many of the links in this article will be outdated at some point. Your production documentation may be outdated, especially if it's not online, but even if it IS online. There is still value in creating it provided you plan for it to be obsolete at some point:

1. Date your work. You don't want someone thinking it's current if it's not.

2. Realize it's dated. Realize that things will, in all likelihood, change.

3. Realize that not everything is known. Therefore, what you write may be right or it may be wrong.

What else can you write about as a developer? I like to write out our post mortems or retrospectives. It keeps me honest. We may continually to come back to wanting to do something that doesn't get done or try something and then decide it doesn't work. I like to create an entry in our Wiki the minute someone asks a question or has a problem, so we can come back to it and try and improve on it later. The writing may be short or long. It may even be wrong.

But most importantly, keep it around. There is nothing worse than losing writing.

There's an added trick you can do when you have written down all those ideas:

Condense a larger piece of writing into a smaller set. 

Think about your audience. No one wants to read a 750 word email - they want to read a three point Powerpoint or a five sentence email.  If you've written your longer piece, then coming up with your three or five points is a lot easier. Because you've thought of the issues, you've carried it through, you've worked out the kinks or at least identified them. Your condensed version will offer a lot more and may inspire more reading and writing. I thank Bill Jensen and Simpler Work for that little tidbit.

But the value in writing out your ideas, and honing that writing to get a point across, will always be useful, to developers, to writers, to teachers, to students, to managers, and sometimes, even just to YOU.

Comments

Popular posts from this blog

Blogs and RSS come to Microsoft.com

MS has just introduced their portal and it's pretty comprehensive. Nothing quite like learning that some people use AIM instead of MSN messenger, or that there really may be a need for supporting 4 monitors ( Cyrus Complains ) However, it's really a great sign that MS is serious about supporting the blogging community which seems to have um, exploded in size in the past year. Blogs and RSS come to Microsoft.com

FoxInCloud Stats

FoxInCloud sent this link a while back about their statistics regarding visits to their site: http://foxincloud.com/blog/2017/12/27/VFP-community-lessons-from-foxincloud-site.html What's interesting here is the breakdown of people. Yes, I think it's understandable that the Fox community is getting older. Another factor is the growth of the mobile and web environments taking over development. These environments really do push people towards the newer non-SQL or free SQL/hosted environments but more towards hosted storage options like Amazon and Google. A tool like FoxInCloud that helps MOVE existing applications to the cloud inherently competes with those environments. But FoxInCloud also allows developers to extend their application further by giving them a starting point using Javascript and the basic CSS (such as Bootstrap). If you're not rebuilding your application from scratch, it's certainly a great step forward. FoxPro VFP

5 Great Reasons to attend Virtual FoxFest

What's coming up? Virtual FoxFest is coming up soon (sessions start October 14th). Like last year, the conference is entirely virtual yet includes great breakdown rooms and sessions to add that nice one-on-one feel that you get in person. It's also staggered so you can choose which days you want to attend - October 14th, 20th and 26th. This is great if you can't break away for a consecutive three days. But really, I've gone through the sessions and I see five great sessions that I'm eager to check out. 1. A Decade of Thor (Rick Schummer) Thor has been an extension for Visual FoxPro that many developers swear by, yet many don't know even exists. Visual FoxPro's built-in extensions are great but Jim Nelson's Thor supercharges your IDE. I can't believe it's been ten years - so Rick's session should be able to not just whet your appetite but give you all the reasons you should be using it. 2. VFP C++ compiler.  Last year, we saw DotNetX as well