4 ms·
I've seem some larger projects at bigger organizations where extensive wikis were available. I'm pretty sure updating docs/wikis was part of the "definition of
by adverbly 6y ago
I've seem some larger projects at bigger organizations where extensive wikis were available. I'm pretty sure updating docs/wikis was part of the "definition of done" on a task. Problem was, most of the devs were terrible, terrible writers. There was little to no consideration made for "explain this as if I don't already understand it" on these pages. They were dry, full of useless generated ERDs and other generated filler, and generally I'd end up reading the source code or reading the integration tests to get a better sense of what was going on.
All in all, I actually agree with you. Knowledge bases are great when done right. But it takes time and a general knack for writing, and that's not something that most devs have from my experience.
- troutwine 6y agoWe ought to work harder at teaching writing. I think there's a definite group of people that really _love_ writing, have a general knack for it and work hard to turn that knack into a talent. But, those folks aside, I've found there's simple tweaks that can be made to most technical writing that greatly improve it. For example, in code documentation explain "why" and not "how". Later source readers will probably be able to understand your code unless it's especially complicated but they will not, from the code, be able to figure out why it exists. Lots of folks write the "how" down though, in part because the external context is taken as a given in the moment -- they're very familiar with it right then and there -- but also because the "how" is probably more interesting than the "why". Empathy for the ignorant is something you see in excellent technical writing, less so in the middling stuff.
- bollu 6y agoDo you have more on how to get better at writing?