09-04-2020, 02:13 PM
(09-03-2020, 10:25 PM)pine76 Wrote: ...
From my perspective as someone who earns his paycheck developing software, documentation is always a problem. Even in commercial products its quality is often severely lacking. Issues vary from outright incorrect information or bad advice, simply outdated info, using marketing materials and pretending it's technical documentation, surface-skimming technical details, making it so you have to read hundreds of pages before you can step through even a basic use case, describing all the basic use cases but omitting anything that can help with any less trivial scenario... And when it comes to internal documentation (various wikis used by the developers inside the team) - that usually is a much bigger mess than external documentation, with most of the knowledge being tribal despite all the valiant efforts to document as much as possible.
Good documentation is rarity. AWS CLI/API docs - kinda suck. Python docs - figuring out what exceptions the code can throw is always a bit of a process. BTW, in my experience IMHO the best documentation I've ever dealt with was PostgreSQL docs - they covered from basic queries through tuning server instance and to using its C API, and you can find both specific use case howzitdones and the more abstract what's happening BTS.
This message was created with 100% recycled electrons