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