Of the Importance of Documenting

It’s not secret that I started a new job and that I’m now working for a closed-source company (even if sometimes I have to work with my beloved Linux, but unfortunately that’s rare).

Before starting, I thought I would have found some great docs, describing the works of others, API documentation, internal guidelines, flow-charts, diagrams, whatever; I thought I would have found the basic “infrastructure” that makes a developer work.

I was wrong.

Actually there is documentation, but it’s only the end-user documentation, no real internal documentation. No documentation to help you speeding up with your work, to understand how things work. No (useful) comments in the code.

What would have taken you 5 days of work to accomplish, (exaggerating) will take you two weeks: you have to ask someone else in the company, but maybe they don’t remember or didn’t write that particular piece of code, or didn’t work on that implementation.

Documentation is important, from the end users to the developers, if you want your project to self sustain, if you want to ease the life of other people, and if you want your project to live a long and prosperous life. People were not in your head (and are not in your head) when you wrote that strange thing. 1-2 years from now you could be working for another company, what would be of other people who are trying to understand what you wrote? How would people easily understand how things work in a complex environment?

But luckily, things they are a-changin’. They are now realizing that they need documentation, that they need documentation in the code, and that they need to document things. A small victory.

Lesson learned: next time you do a job interview, if you don’t know the company, ask what are their internal standards, guidelines, and if there is documentation. You can understand a little bit of the level of professionalism of it.

6 commenti
  1. I was quite surprised with this as well when I first started my current job at a proprietary software company.

    Worse of all, it seems to be culturally expected in the badly managed companies not to document, so that employees can ensure they keep their jobs as it makes it more difficult to replace them.

  2. Milo ha detto:

    @Jackflap:
    Totally agree. But from my POV, the end result of this it’s exactly the opposite (at least for people that have experience in the open-source world): they make you think about looking for another job, ASAP.

Lascia un commento

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione / Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione / Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione / Modifica )

Google+ photo

Stai commentando usando il tuo account Google+. Chiudi sessione / Modifica )

Connessione a %s...

%d blogger cliccano Mi Piace per questo: