3 ms·
> Why? Why do you not have documentation? > Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonst
by chaps 2y ago
> Why? Why do you not have documentation?
> Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness.
You answered your own question :)
- worik 2y ago> You answered your own question :) So "do not do the hard parts"? That is very unprofessional
- golergka 2y agoAchieving desired result is professional. And achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome.
- worik 2y ago> Achieving desired result is professional. No. It is geeking out, part of the job... > achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome. That is a menace. I think I am working on code you wrote It is the opposite of professional. It is amateur, irresponsible dilettantism
- floating-io 2y ago"Professional" is doing what they're paying you for, end of story. Most employers have less than zero interest in paying coders to document in my experience. If they want documentation to exist, they hire a technical writer. Sadly, I've never met an employed tech writer (and no, journalists don't count).
- Tainnor 2y agoYou're not being paid to document, you're being paid for writing maintainable code (in decent places at least) and it's your job as a professional to decide how much documentation that includes. In my opinion the idea that good code is "self-documenting" is a myth.
- golergka 2y ago> ...to fight and conquer in all your battles is not supreme excellence; supreme excellence consists in breaking the enemy’s resistance without fighting
- nicce 2y agoThere is a limited time available. The root comment was getting success with other means. Adding good documentation would have costed much more time. That might have made their projects less successful in this case.
- worik 2y ago> Adding good documentation would have costed much more time That is the problem Not that it is true, it is not, for many reasons. It is a problem that is believed
- bdangubic 2y agocosted more = it would take time. you have magic ways in which good documentation can be created without any time at all allocated to the effort?
- Tainnor 2y agoThe cheapest time to add documentation is when you have the information in your head because you just worked on it. Nobody is demanding an essay for every method, but just write down what went through your head when you implemented weird hack #17 or found out that the API you're calling does something surprising.
- nicce 2y agoThe main challenge is that you would need to write the documentation for a person who might have never used this particular software before. The information that is in your head might be nonsense for this person, and there is chance that it is not reducing the time it takes to understand in a meaningful way.
- Tainnor 2y agoIt's a best effort thing - as anything in software.
- chaps 2y agoUnprofessional to who, exactly? Like a sister comment says, an understandable system was built, so it seems like a strong professional relationship existed. Every codebase is going to have different definitions of "professional standards".