Slightly off topic, but that article should be required reading for anybody writing documentation. Wouldn't it be nice when trying to use some new framework or device if the writer not only imparted knowledge of the product but also the underlying principles that make it work!
Instead you get some huge corporation like Apple or Microsoft whose idea of documentation is some kind of rigid recipe stuck on their website that is out of date or missing some critical step that the writer assumes is common knowledge. Or Texas Instruments woeful bluetooth stack where the documentation is basically their online forum, a giant heap of misery where perplexed engineers are advised to check if the device has power and if it does, can they reproduce the error on the 2017 release before the Ti engineers get involved.
As an example I just abandoned trying to set up a cross platform app in xamarin for this reason. Flutter docs are much better so even if its rubbish I am already further along.
> huge corporation like Apple or Microsoft whose idea of documentation is some kind of rigid recipe stuck on their website that is out of date or missing some critical step that the writer assumes is common knowledge.
Microsoft at least is very “dynamic” in their documentation. In one scenario, we had a case open for a product that was implemented within the documented limits, but not working.
Then the ticket was closed — the documentation was changed to a threshold that happened to line up with our previous, working workload.
Instead you get some huge corporation like Apple or Microsoft whose idea of documentation is some kind of rigid recipe stuck on their website that is out of date or missing some critical step that the writer assumes is common knowledge. Or Texas Instruments woeful bluetooth stack where the documentation is basically their online forum, a giant heap of misery where perplexed engineers are advised to check if the device has power and if it does, can they reproduce the error on the 2017 release before the Ti engineers get involved.
As an example I just abandoned trying to set up a cross platform app in xamarin for this reason. Flutter docs are much better so even if its rubbish I am already further along.