3 ms·
> There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have before. What did you expect? Nowadays, ther
by ysavir 10y ago
> There is more stuff available, true, but the quality of documentation is abysmal compared to what we used to have before.
What did you expect? Nowadays, there is a common expectation, especially among web development libraries, for frequent updates, especially in the cases of bugs, etc. In the eyes of the people, functionality became more important than the documentation (though those people would like to claim otherwise, I'm sure).
The demand is for the new code to be available ASAP. And as a result, the documentation suffers, and the implementations and details change faster than the documentation can be maintained.
The emphasis of maintaining good documentation is further lessened by sources like StackOverflow, which provide the library maintainers with an excuse of "we can skip this step, since it will be covered in SO and countless blogs anyway. It's not like we're the only source of information."
This is just an unfortunate symptom of the modern coding ecosystem. Good documentation requires stability and consistency, which today are discouraged in favor of flexibility and quick turnovers.
- softawre 10y ago> Good documentation requires stability and consistency Or a good architecture, a decent generation system, and a bit of discipline to write out the non-obvious bits that can't be generated.
- sklogic 10y agoDocumentation should not suffer from frequent changes. It is easy to keep docstrings in sync with the implementation, they should both be visible at the same moment. Also, if 99.9% of all those "web frameworks" just die without a trace, the world will become a much better place anyway.