On 22 Nov 2016 at 10:54, Paul A. Bristow wrote:
1. Does it make sense?
Amazing that something as handling the unexpected can be complicated, but yes, I think it does.
As you and others have observed, explaining the "evolution of ideas" is too convoluted with the 'how to do it now'.
Splitting the documentation into "What it is and how to do it" from "Why it's like this and how it is better" is one way. Re-ordering could also work.
For users, start with the very, very, very simple to prevent TL;DRitus switching readers off.
Working examples that the user can pull and run will sell well.
Thanks for the feedback Paul. Much appreciated. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/