[jjsaw5]

Love it? Hate it?

Everyone has different feelings on documenting things they work on or with. I personally am a big fan of documenting what i can. It helps me out when i have to revisit something and i have a document with some notes and screen shots that will help me out.

Example: you handled a incident were a server crashed. You documented your steps to resolve it and stash it away somewhere. 10 months later the server crashes again and its the same scenario. It's nice to have something to look back on in case you don't remember what you did 10 months ago.


So what do you document? How detailed are you? What do you feel it's importance is within IT? Does your employer require you to do it?

Discuss.

[Kilorn]

I hate having to do tons of documentation, but a saying that has stuck with me is "If you didn't write it down, you didn't do it."

[codeprada]

I personally only document the code that I have to share or really can't duplicate again. Most times in my projects I can look at any piece of code I've written and know exactly what it does.

[NeoTifa]

Heh, I comment my code so much I get yelled at for it. I also tend to write logs to track what I did during a coding session on personal projects.

[AdamSpeight2008]

Documentation is for other people.

Imagine trying to program java without the java documentation, or on the Microsoft platforms with MSDN.

This post has been edited by AdamSpeight2008: 25 August 2011 - 11:58 AM

[Draps]

I personally don't mind documentation. It has it's uses if you have a large class with a few hundred lines, and you are looking for something quickly or you have forgotten a certain aspect of why you wrote it 'that way'.

However if I am writing for a company or as a collaborative team i document to a higher level. People don't seem to get too upset.

In terms of documentation for networking/security is a must!, My Cisco CCNA course taught me one thing about advanced networks.. They crash and mess up a lot. When it comes to a companies network they want it back up and running ASAP. (Usually its some idiot who cant connect to the network and complains it's down. He switched his IP phone cable and PC Ethernet cables in the sockets on the wall for 'Their Convenience'... Sigh)

NeoTifa, on 26 August 2011 - 04:55 AM, said:

Heh, I comment my code so much I get yelled at for it. I also tend to write logs to track what I did during a coding session on personal projects.

logs sound like an awesome idea!

[Craig328]

I comment my code where it seems necessary. I use SVN so if I need to reconstruct what I did, I have a nice commit log. I'm also frequently asked to deploy application modules to non-tech users so I typically end up writing a "how-to-use" step by step instruction series.

That last one is actually kind of handy from time to time as it's not until you have to explain a new tool to someone else that you maybe see places where you could have made its implementation easier.

[AdamSpeight2008]

Comments are only part of Documentation.

- Specification
- Reference Manual
- User Guide

[elgose]

AdamSpeight2008 said:

Comments are only part of Documentation.

This. Plus it seems the original post was directed specifically at the other forms of documentation.

AdamSpeight2008, on 25 August 2011 - 11:56 AM, said:

Documentation is for other people.
...

People love it when I provide screen-shots and detailed instructions for various tasks. And while I feel I can get by with most tasks with proper text-only instructions (or even vague guidance), seeing beautiful instructions with screen-shots can make the job so much better. I usually don't go as far as documenting what I did to fix some problem like jjsaw5, although when something identical happens months down the road I often wish I had. Problem is, I think I'd end up with so many documents that it'd be pretty difficult to navigate and find what I need, and most likely I'd never touch 99% of them, which would be a lot of time wasted for something I'd never use again.


I also tend to use a lot of custom in-house applications, many of which are prototypes and constantly changing. My awesome informational document or wonderful how-to might be useless, or downright wrong, in a matter of weeks due to changes.

[Nightfish]

I'm a big proponent of documentation. Yes, perhaps you know what your code does, but what if you're no longer part of the project? I like to make my stuff as easy to pick up for someone else as possible. Even with this current project in which I'm all but forbidden to document stuff I try to work around that. (forbidden to have a project plan... recipe for disaster anyone? D: ) My variables have rather long names, but they tell you what's inside. My methods have a comment saying what goes in and what comes out and maybe even a little about what happens within.

On the other end, I like to make a screenshot of my GUI and provide the end user with some info about what that thing does. It's super obvious to me, but that might just be because I spent weeks / months developing it and watched the application grow bit by bit. If you get hit by the whole thing at once, odds are it's not as obvious anymore.

[Tayacan]

I'm actually getting in the habit of at least commenting my code thoroughly - not so much to explain how a piece of code works, but more to explain how to use it so I won't have to remember exactly how it works. And I'll write it down whenever I write weird code, like some of the css stuff you have to do to work around Internet Explorer (does anyone know a nice way to have invisible elements that are clickable? Best I could figure out was giving it a color and making it transparent).

Also, I'm currently working on a website for a small firm, and I'm documenting everything in case someone else has to take over at some point.