undefined | Better HN

0 pointsjrockway5y ago0 comments

Explaining how you did the thing that you already did cuts into the time for building the next thing. The difficulty that people wrestle with isn't whether or not documenting something is valuable, but rather whether documenting that thing should cut into their sleep, recreational activity, or The Next Thing.

0 comments

bitboop5y ago

Personally, I'd rather not immediately jump into building the next thing. After having worked on any significant project, I find writing documentation helpful on a selfish level: I use it to wind down and let my brain idle for a while. I don't think it's a good thing to go full tilt from building one thing to the next. It's good to pause in between, appreciate what's been accomplished, reflect on lessons learned, and take a well deserved break. I find writing documentation an excellent vehicle for that.

actinium2265y ago

What??

I look at it like this: explaining how you did the thing is part of doing the thing, so it's not complete until it's explained well enough for whoever your audience is. Not writing documentation cuts into time for doing the thing, i.e. cutting corners.

Kinrany5y ago

This had nothing to do with the topic: some people don't want to write documentation.

ljm5y ago

Or aren't given a good reason to do it.

I don't really enjoy writing tests at the best of times, for example, because I've never had the enjoyment of inheriting a readable test suite. Most of the time you're looking at coverage hacks that test the runtime and, hopefully, cover some behaviour, and you're lucky if they can give you confidence through a refactoring. Mocks and stubs and spies are helpful tools but I've lost count of the amount of times that the actual purpose of the test is faked without anybody realising it.

But now, this time, there is a purpose and also organisational remit to change this situation and I'm going all in on rebuilding test architecture and writing examples of what we want to see. I'm actually enjoying something I never really enjoyed.

So it is with documentation, or dealing with bugs, or tech debt, or anything like that. It's not really about want or don't want, but why... and if you're on board with the why then it's gonna be better for you than if you're not.

That, of course, depends on solid leadership. So ultimately you're looking at how tight your org ship is.

ipaddr5y ago

Most because translating code to english requires changing mindset.

XorNot5y ago

The problem is documentation is a different skillset to coding. Spend enough time doing only documentation and suddenly you're no longer a programmer, you're a documentation writer.

j / k navigate · click thread line to collapse