Re: GNATCOLL JSON Parsing

[gautier_niouzes@hotmail.com]

On Monday, December 3, 2018 at 9:48:59 PM UTC+1, Olivier Henley wrote:

> I do not believe in 90's doc, a la MySQL, where you have to read dozens and dozens of official doc to make a simple query or just to install it. No, what is proper doc these days, is hands-on toy demo. You build it, inspect a couple of files, you get the picture, c&p the basic code and expand from that. You can keep rolling.

IMHO, both (doc and demos) are necessary.
I elaborate a bit (experience gathered over years, including from more or less polite but mostly helpful feedback):

1) the demo tree in 2 layers:
1.1) a bunch of minimal toy demos (max 50 lines) and pointers to 1.2
1.2) a few larger applications (ideally, useful)

2) the doc tree in 3 layers:
2.1) readme, with a short summary and a pointer to 2.2
2.2) a larger doc in one file with build instructions and pointers to 2.3
2.3) technical documentation

The demos are crucial if you want to have people have any interest at your project.
Even in the 80's (so, before the Web and GitHub ;-) ), successful software had lots of demos.
The demos need to build and run out-of-the-box (or the author(s) need to explain very clearly what are the dependencies to other libraries).
The test process includes packaging the project, copying to another computer, unpack, build and run as if you (the author) were a newcomer - of course this is very difficult to do it yourself, but better than not trying it (there are some tricks to improve randomness in that phase)...

The demos show much of a project's health and portability - outside the computer it has been developed on!

Disclaimer: probably I forget to follow these rules. Feedback is always welcome...