Hacker News Reader

Some times tests, but sometimes I start writing/improving the docs and tutorials, if they are in a bad shape. Mostly they are.

Plus of course improving the infrastructure. This is also mostly in the same poor shape as the docs.

View on HN

Yeah, whenever new hires complain about the lack of completeness or correctness of documentation, I'm like: that's a great place for you to start. It also seems to be a great signal of the attitude of the new hire, because the people who kind of groan at that task usually end up having problems.. but that's another topic altogether.

As a (junior) new hire in a group without very complete or correct documentation, I'm not sure I can agree with that. It can be nigh on impossible to try to improve documentation for complex systems without a very deep understanding of the stack. I could spend hours writing documentation but it's not useful when I don't know what is and isn't an intended behavior. I think a fresh face is a great asset to have for writing docs but they need someone with a very good understanding of the system to work with them. Some of the most frustrating times I've had had a junior dev have been documentation tasks for things I did not know very well, spending time poking the system to gain understanding and more time writing clear docs, only to hear that my docs are 'not how it works' and I had either setup and configuration wrong or need to file bugs so it works how it's 'supposed to', even though that is the exact documentation it's lacking. Maybe this is different for projects with less technical debt, where if the current behavior was documented that documentation would be useful. I think this habit of giving documentation tasks to the least knowledgeable people on a project, even though it's reviewed by those with more knowledge, makes the docs suffer.

Reply on news.ycombinator.com