DevOps and Documentation (or not!)

I've always found most organisations and engineers are bad when it comes to documentation, but how can we improve on that? Can we ever get it right?

[luisrodriguezgarcia]

I like so much these kinds of topics, they are not very technical but are a big part of our daily work life. I encourage you to keep it up.
Regarding to documentation topic in my case, we leave the responsibility of the documentation to the one in charge of the project and we don't consider the project over until the documentation is done and also validated by another member of the team.
From my personal point of view when I write documentation, I'm trying to do it thinking of someone who joins up to our team tomorrow... The idea (maybe a bit selfish) is the new guy be able to understand why and what we did and he/she doesn't need my help for that.
When the documentation is part of the process of deploying for any project can not be ignored.

[dreamcat]

i think you hit the nail on the head there: when you discover insufficient documentation, then it's probably best solution to request some pair programming sessions. and have a working through with an existing team member. because not only does it help you, it also helps a pre-existing member of the team (before you joined up) to then see your pov / and be something or somewhat on your side / take your perspective / see your views represented by an established team member. and that side is probably at least as valuable to the situation as you yourself learning and becoming familiar with the environment. it then gives a good basis for further understandings or discussions / justifications to re-assess or place some level of appropriate value as to how much can or should be documented at the time. or to what extent that you can obtain the best value-for-time-spent to at least cover the lowest hanging fruit. in a fashion that forms a good entry point and familiarization. but without overly or too comprehensively documenting stuff that ultimately is less needed. it can even be something as simple as justifying to the boss some extra hours to actually do it. or give some slack in the bringing up, or to better assess fair progress in the bringing up. but most of all: and just like you say not to be left in a black hole, or too embarrased to ask things which you are supposed to know. and feel shut out of some voodoo secrets that everybody else goes by and relies upon to actually do the job and it's core tasks.

i feel there is a natural predisposition to under-document. in order (mostly speaking, as a gross generalization) to keep individual job security. but also because it simple isnt fun, and isn't really recognized or rewarded as metricized productive output. however with the pair programming sessions suggestions. it really puts home a feeling that you want to work with this individual, that they are your co-worker in the same boat as you. that you need to invest and protect them as an individual, who is basically somebody you wants to work with and keep around in the workplace. of course if your co-worker hates you, and has it in for you, the situation could equally be entirely different, so to bear that in mind also, those workplace frictions can also exist, that your ymmv ;)

[IlSqueak]

Hear! Hear!
In my many roles documentation has always been neglected. From big companies to small ones, everything useful always lives in that guy over there's head.
Many companies claim to embrace one single location for documentation, and some embrace it to the point of having 5 or 6 different single locations for documentation, none of which are up to date.
My current gig which i started 3 weeks ago hasn't got a single line written anywhere.
I'm fixing it: Everything I learn is being written down, even to the point of what printers are where, and what sort of ink or toner cartridges they take. I will bring this place up to scratch!