Does documenting feel productive?

Do you think that people see value in writing documentation?

If not, why not?

If so, why don't we do it more?

Are we not given the time? Can it be about (language or writing) skills?

Is it really just about time?

Thanks for your thoughts!

Comments

[dastasoft]

It is definitely necessary, especially in companies where there is a medium-high rotation of personnel.

I have been in places where some workers felt untouchable because they possessed knowledge that no one else had, while at the same time complaining that they always had to go through them to make certain developments.

It's a matter of time but there's a big component of discipline and having the routine to do it. Even though we all know that when time is running out, the first thing that is removed from planning is documentation.

Perhaps it is a mistake to think that the one who does the development should document it, since not everyone has the same communication skills or the will to do it and it should be delegated to a specific profile within the team.

[Ben Halpern]

I have been in places where some workers felt untouchable because they possessed knowledge that no one else had, while at the same time complaining that they always had to go through them to make certain developments.

This is exactly what documentation is for.

The Problem With Heroes In Software Development

Beekey Cheung ・ Sep 23 '17 ・ 5 min read

I think good documentation can be inherently really really hard. Communication is tough, keeping things in sync is easier said than done, and hierarchy/reading order is just not easy to figure out when it's evolving at any time.

Unlike a self-containing blog post or book, docs can be random-access and getting it right is a skill that is hard to come by.

[Jaxcoder]

I don’t like those devs that keep everything to them. I try to share everything I know with everybody I work with on my immediate team so I always have back up for the company.

And yes getting it right it’s very difficult and a talent in itself.

[Spyros Argalias]

There is definitely value in writing documentation. Documentation about the implementation is mostly: "I might forget how this works, so I'm writing my notes here so I can see it later."

There is more documentation such as:

• An overview / tour of the codebase for newcomers or people that haven't used a particular area.
• Why a particular implementation was chosen.
• Tons of non-technical documentation about the project, why some decisions were made, design documentation, tons of stuff in general.

It's all useful.

Why is it bothersome? In my opinion:

1. Because it would be better if it wasn't needed. As mentioned, a lot of it is comments for stuff that wouldn't be immediately obvious without it.
2. Because we don't want to write long documents for why X was done and to document what we're doing. We just want to do the work.
3. It needs constant maintenance... Outdated documentation could be worse than no documentation, because it can be confusing and misleading.

I'm curious to see other answers, as these are just my personal experiences.

[Jaxcoder]

I think there is a total value in writing the documentation but I just don’t like doing it.