Documentation aaaaarrrrgggggg
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
We are used to writing for a smarter user-base than the documentation's target audience.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
I usually try to enforce a code freeze a few weeks before release. (depending on the size and complexity of the package). In that time I make sure to write the documentation and create install procedures and the like. :rolleyes:
V.
(MQOTD rules and previous solutions) -
We are used to writing for a smarter user-base than the documentation's target audience.
The problem is I understand what I write but few others do. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
My code is self-documenting :D I hate documenting my code (i.e. writing manuals), unless it is to teach others how to use a certain technology (like in my blog or articles). And I'm not particulary bad at it. But I do have a degree in Media and Journalism, so I may not be your average documentor :D
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
} -
My code is self-documenting :D I hate documenting my code (i.e. writing manuals), unless it is to teach others how to use a certain technology (like in my blog or articles). And I'm not particulary bad at it. But I do have a degree in Media and Journalism, so I may not be your average documentor :D
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}Sander Rossel wrote:
My code is self-documenting
As it should be. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
Mike Hankey wrote:
Why is it that we as programmers hate to document?
I must be some weird outlier because I actually quite enjoy documenting, everything from story boarding to code docs to architecture acceptance test procedures (probably nobody has heard of those things nowadays) to user manuals. One thing that's fun about documentation is that I often have the experience "oh wow, I could have done that so much better this way." I also find it interesting, in a sort of sad way, how little pre-code documentation is written, stuff like architecture, diagrams of component interactions, etc. To me, that stuff is like writing an outline to a book -- if you do it well, the book basically writes itself afterwards. Same with architecture / design docs -- do it well and the code "just happens." Sure, there are always sticky areas, but overall, that's been my experience. Then again, we really don't have decent tools for a) documenting from code and b) coding from documentation. Even simple things like diagramming a state system or inter-module events, where are the tools to generate the code in a language agnostic way but still cognizant of the language features and framework the dev wants to work in? They don't exist. What I find tedious is not the documentation, but having a pretty diagram in Visio and then having to write the damn code, when I should have a tool to at least generate 90% of the code for me! Anyways, enough of that soapbox. :) Marc
Imperative to Functional Programming Succinctly Contributors Wanted for Higher Order Programming Project!
-
Mike Hankey wrote:
Why is it that we as programmers hate to document?
I must be some weird outlier because I actually quite enjoy documenting, everything from story boarding to code docs to architecture acceptance test procedures (probably nobody has heard of those things nowadays) to user manuals. One thing that's fun about documentation is that I often have the experience "oh wow, I could have done that so much better this way." I also find it interesting, in a sort of sad way, how little pre-code documentation is written, stuff like architecture, diagrams of component interactions, etc. To me, that stuff is like writing an outline to a book -- if you do it well, the book basically writes itself afterwards. Same with architecture / design docs -- do it well and the code "just happens." Sure, there are always sticky areas, but overall, that's been my experience. Then again, we really don't have decent tools for a) documenting from code and b) coding from documentation. Even simple things like diagramming a state system or inter-module events, where are the tools to generate the code in a language agnostic way but still cognizant of the language features and framework the dev wants to work in? They don't exist. What I find tedious is not the documentation, but having a pretty diagram in Visio and then having to write the damn code, when I should have a tool to at least generate 90% of the code for me! Anyways, enough of that soapbox. :) Marc
Imperative to Functional Programming Succinctly Contributors Wanted for Higher Order Programming Project!
I agree documentation tools are pretty much non existent, pity would really help poor souls like me. I think my biggest problem is my grasp of the English language. One tends to fear what one does not understand. You, Sasha, Nish and others have a writing style that I envy. I excel in other areas; trivia, kick the can, distance spitting, etc.. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
I agree documentation tools are pretty much non existent, pity would really help poor souls like me. I think my biggest problem is my grasp of the English language. One tends to fear what one does not understand. You, Sasha, Nish and others have a writing style that I envy. I excel in other areas; trivia, kick the can, distance spitting, etc.. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
Self Documenting Code... I always thought it was a buzz word way to get out of using comments/documentation, I have hardware projects to take over that were self documenting apart from the input, power amp it wasn't! same with code 'Oh I see what is being done, but why?' is a common in my experience! :wtf:
-
Self Documenting Code... I always thought it was a buzz word way to get out of using comments/documentation, I have hardware projects to take over that were self documenting apart from the input, power amp it wasn't! same with code 'Oh I see what is being done, but why?' is a common in my experience! :wtf:
I'm finding that with hardware I need to document also but in a different way; I keep notes, schematics, images of the final product, etc. then when I go back some time later it is a lot easier to remember seeing that I have the CRS syndrome.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
You don't get paid enough to document code. I'm looking at very sparse data array of informative statistics about contacts from my landlord warning me of imminent water shut offs. I see four notices over a years' time, and only two of them in which the water was indeed shut off. How is this data? It's uninteresting PLUS it's only pseudo valuable in that it contains only partial information about what it's entitled to contain. Perhaps if the water really did get shut off, I'd be happier about being notified.
-
You don't get paid enough to document code. I'm looking at very sparse data array of informative statistics about contacts from my landlord warning me of imminent water shut offs. I see four notices over a years' time, and only two of them in which the water was indeed shut off. How is this data? It's uninteresting PLUS it's only pseudo valuable in that it contains only partial information about what it's entitled to contain. Perhaps if the water really did get shut off, I'd be happier about being notified.
RedDk wrote:
You don't get paid enough to document code.
I don't get paid anything for writing code, I do it for the fun of it.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
The problem is I understand what I write but few others do. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
I have enjoyed writing doco precisely once in my entire life, in the early 90s I got paid approx $5k to build an app. In the late 90s they wanted to rewrite it into Delphi, when I refused they asked me to write the technical spec so their coders could work from it, I charged $20k and laughed all the way to the bank. It is the only time I think I have actually done a good job of doco, they got their moneys worth.
Never underestimate the power of human stupidity RAH
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
Mike Hankey wrote:
Why is it that we as programmers hate to document?
I wonder if there is a correlation between the dislike for wanting to write documentation and writing research papers. I don't care for writing documentation and I never cared much for writing research papers in college. I had to do it, but I didn't like it. Thus, my hypothesis is, if you like writing in general, you will not mind writing documentation. :-D
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
When I first started in the industry, the standard was that documentation was to be completed before the first line of code. Some refer to that method as the waterfall method. Today, you seldom see documentation; or, what little there is seldom reflects the product for which it is written. As a basic rule of thumb, write your documentation for an eight-year-old. (I used to have my daughter do the final edit of my documentation until she was eleven.)
-
We are used to writing for a smarter user-base than the documentation's target audience.
Tragic and true.
Mislim, dakle jeo sam.
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
-
The problem is I understand what I write but few others do. :)
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
I've noticed that Mike. ;P
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
-
My code is self-documenting :D I hate documenting my code (i.e. writing manuals), unless it is to teach others how to use a certain technology (like in my blog or articles). And I'm not particulary bad at it. But I do have a degree in Media and Journalism, so I may not be your average documentor :D
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}The Documentors - weren't that nasties in Harry Potter?
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
