re: what bothers you the most of being a programmer? VIEW POST

FULL DISCUSSION
 

Something that bugs me a lot is the proliferation of frameworks that are too clever for their own good, and the tendency for everything to be written in whatever framework happens to be the hottest that week (and of course that framework we were using LAST week is now total poop). Unfortunately this means that either you're ending up rewriting everything constantly, or whenever you inherit some older code it's in some framework that nobody knows anymore.

Relatedly I am getting very frustrated with "self-documenting" things or things which are only explained in circular terms with respect of other parts of the system. I've recently been reintroduced to the Perl ecosystem and I feel like everything is written with the mindset that everyone who uses this thing is already an expert in all of the things that this thing is trying to replace. And of course nothing is ever on the project's own website (even for web frameworks!), it's all documented in a twisty little maze of Perldocs, all alike (except that they differ by version and it's hard to tell which version is the one you're using).

Poor documentation in general is I guess my main frustration. I'm accustomed to designing systems by writing the docs for a feature in tandem with designing the feature itself (not before prototyping, but as part of describing the prototype for future users who I am trying to convince to use the feature), and using that to reason out where things make sense. I feel like most software I try to use on a daily basis is not documented or designed that way, and instead it's just like, "Well, this works, here's a bunch of examples about how to use it" without any description of what anything in the example is doing either.

Or worse yet, the only docs that are available will be wrong or woefully out-of-date or misleading or "technically correct" (which is the best kind of correct) but not actually useful.

So, yeah. Please, document your stuff as if you're explaining to others how to use it. Or if you aren't good at writing documentation, explain it to someone else and have them write the docs, and then if they document it wrong, explain it until they document it right! Remember that software is for people; the machines that run it are just tools.

code of conduct - report abuse