The uber-importance of software documentation
[removed]
Posted Jul 28, 2021, 4:00 PM UTC
611
ALL of the roles that contribute to a software product are important. Docs, QA, PM, the works. It takes a village, etc.
However, all the supporting roles, including docs, have no purpose without someone (the devs) creating the product. Having worked as both a dev and a writer, writing is much more straightforward, IMO.
That's not to say the documentation isn't important. I passionately believe it is. That's why I changed fields. However, the level of difficulty and expertise required is not equivalent, IMO.
Now, one can argue that devs are overpaid. I certainly felt that was true when I was one. I could get behind the idea of more equity between the roles, but not writers > devs.
6
[deleted]
1
Totally agree. Now tell that to my employer. My SME get paid about ~250k, I get ~130k.
1
That is more than triple what I make, if that helps at all lol
1
40k? Dude. Leave.
1
Would have been nice to read the article, but the website told me I'd hit my limit of free articles for the month before I finished the first paragraph (which is odd since I haven't been to that website in at least 3 years). So I'm just going to assume it says nice things about documentation, and hope that folks who do read it think it makes a good point.
1
"Docs, says Human Security’s Bethann Noble, “are a fundamental part of product.” You don’t have good docs, you shouldn’t ship."
Well, you'd think so, but often software is developed by one group of geeks and used by another group of geeks, who may well fathom it out despite the substandard documentation and, if they're really stuck, contact tech support.
And the sole criteria for the project manager is, "Is it documented?" if the answer is yes, then the manager has little interest in whether it's any good.
1
As internet inventor Al Gore famously said, "Never put the cart before the horse."
1
Likely to be an unpopular opinion here, but I don't think writers will every be paid more than engineers - nor should they.
The role is very important, adds incredible value, is multi-faceted in use, etc. The list can go on and on. However, the doc is meaningless without the code/software/equipment/subject matter.
I think the point is that a good writer is a more scarce commodity.
I don't know if that's actually true. But if it's actually harder to hire a good writer then the market should reflect that.
That very well may be the point of the article, but just because a commodity is scare doesn't mean it actually demands more in the market.
The hard truth of the matter is, software can exist without doc. And does all the time. However, doc has no use without the software. And it's not just software.. it goes for everything. Like, what good is a LEGO manual without the LEGO?
I hate to say it, but for the vast majority of our work, if we all vanished tomorrow life would go on. Users would figure it out. Devs would write their shit doc and it would be enough, even though 93% of it would be viewed as bad. However, if the devs all vanished....
End of the day, you can be the rarest commodity in the world, but that alone doesn't drive your market value.
Not to mention, good writers do make very good money. According the article I'm doing better than the top quartile of software devs, 136K, and I don't live on a coast. I'd also love to see what the top quartile of writers earn. Oddly enough they leave that out, and I feel like it's an important data point, while clearly stating (and citing) it is less than what devs make.
(link above taken from a reference in the article in the OP)
Akin to cheerleading: Without a sport, they've nothing to cheer.
And I do recall an NFL team's cheerleading squad demanding (almost) equal pay, full benefits, etc. They were never seen again.