Comments on: Twelve Lessons From Writing Documentation http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/ Jeff Staddon on Business and Technology Sun, 12 Jul 2009 17:41:26 +0000 http://wordpress.com/ hourly 1 By: [Traduction] La documentation vous apprend 12 choses « Opensource et Web2.0 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-824 [Traduction] La documentation vous apprend 12 choses « Opensource et Web2.0 Mon, 12 May 2008 13:02:51 +0000 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-824 [...] Publié le mai 12, 2008 par Sarah Haïm-Lubczanski Ce qui suit est une traduction libre du billet Twelve Lessons From Writing Documentation de Jeff Staddon, paru en novembre [...] [...] Publié le mai 12, 2008 par Sarah Haïm-Lubczanski Ce qui suit est une traduction libre du billet Twelve Lessons From Writing Documentation de Jeff Staddon, paru en novembre [...]

]]> By: James Lloyd http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-538 James Lloyd Thu, 22 Nov 2007 03:28:27 +0000 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-538 My motivation for documentation is two fold: 1. Remind myself when I forget how I did something. 2. Gives me a convenient place to point people when I don't want to do something: "everything you need to know is on the wiki". My motivation for documentation is two fold:

1. Remind myself when I forget how I did something.
2. Gives me a convenient place to point people when I don’t want to do something: “everything you need to know is on the wiki”.

]]> By: Stephane Grenier http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-524 Stephane Grenier Mon, 19 Nov 2007 15:34:10 +0000 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-524 Hi Jeff, Great post! And I can't agree enough with you that a wiki is great documentation tool. It's much better than a shared directory of documents. Not only that, it really facilitates a lot of the good suggestions you give (such as breaking it down, etc.). Regard, Steph Hi Jeff,

Great post! And I can’t agree enough with you that a wiki is great documentation tool. It’s much better than a shared directory of documents. Not only that, it really facilitates a lot of the good suggestions you give (such as breaking it down, etc.).

Regard,
Steph

]]> By: Soon Hui http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-519 Soon Hui Mon, 19 Nov 2007 00:28:34 +0000 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-519 Nice post, Jeff. I did try to document my code, using various tools, including plain Microsoft Word, Microsoft Visio and XML in-code comments. I must admit that none of these worked very well. Even the XML in-code comments had very little usefullness because more often than not, I didn't bother to update any documentation when my code underwent changes. And you know, dead comments are useless at best and misleading at worst. So now instead of trying to explain what the code is doing or why it is there, I tend to rely on short methods to self document. After all, the documentation that really counts, is the code itself. However, there is one place where I document my code religiously-- The related bug numbers in a bug tracking repository of a test case. It is really useful because it allows me to understand what the test case is doing and why it is there. Nice post, Jeff.

I did try to document my code, using various tools, including plain Microsoft Word, Microsoft Visio and XML in-code comments. I must admit that none of these worked very well. Even the XML in-code comments had very little usefullness because more often than not, I didn’t bother to update any documentation when my code underwent changes. And you know, dead comments are useless at best and misleading at worst.

So now instead of trying to explain what the code is doing or why it is there, I tend to rely on short methods to self document. After all, the documentation that really counts, is the code itself.

However, there is one place where I document my code religiously– The related bug numbers in a bug tracking repository of a test case. It is really useful because it allows me to understand what the test case is doing and why it is there.

]]> By: Mike Coon http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-517 Mike Coon Sun, 18 Nov 2007 21:35:33 +0000 http://jeffspost.wordpress.com/2007/11/18/twelve-lessons-from-writing-documentation/#comment-517 One comment about using hyperlinks. I like to create documents in an outline form and put the detail in a linked doc. That way I can write something like 'Create Build List' as one of many steps with a link that a new user can go to for the detailed instructions on how to do it. Mike One comment about using hyperlinks. I like to create documents in an outline form and put the detail in a linked doc. That way I can write something like ‘Create Build List’ as one of many steps with a link that a new user can go to for the detailed instructions on how to do it.

Mike

]]>