From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM autolearn=unavailable autolearn_force=no version=3.4.4 X-Received: by 2002:a02:c90a:: with SMTP id t10mr15096428jao.19.1543918451351; Tue, 04 Dec 2018 02:14:11 -0800 (PST) X-Received: by 2002:a9d:bd5:: with SMTP id 79mr315222oth.7.1543918451219; Tue, 04 Dec 2018 02:14:11 -0800 (PST) Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!news.gegeweb.eu!gegeweb.org!fdn.fr!proxad.net!feeder1-2.proxad.net!209.85.166.216.MISMATCH!q69no39850itb.0!news-out.google.com!v141ni75ita.0!nntp.google.com!q69no39847itb.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Tue, 4 Dec 2018 02:14:10 -0800 (PST) In-Reply-To: Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=2a02:1206:451b:5870:69b9:9194:344f:1790; posting-account=gRqrnQkAAAAC_02ynnhqGk1VRQlve6ZG NNTP-Posting-Host: 2a02:1206:451b:5870:69b9:9194:344f:1790 References: <9524b3ee-476f-4af6-ab83-b15a6c2a417c@googlegroups.com> <6508fa19-5b93-471a-8b06-216907736b1b@googlegroups.com> <960eb922-6ea5-47d6-af48-289fff1f6fb5@googlegroups.com> <31d76c8f-5e0b-4f64-88fd-34dcd63c19d6@googlegroups.com> User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: Subject: Re: GNATCOLL JSON Parsing From: gautier_niouzes@hotmail.com Injection-Date: Tue, 04 Dec 2018 10:14:11 +0000 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Xref: reader01.eternal-september.org comp.lang.ada:54945 Date: 2018-12-04T02:14:10-08:00 List-Id: 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 a= nd 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 l= ess 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 ex= plain very clearly what are the dependencies to other libraries). The test process includes packaging the project, copying to another compute= r, 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 (t= here are some tricks to improve randomness in that phase)... The demos show much of a project's health and portability - outside the com= puter it has been developed on! Disclaimer: probably I forget to follow these rules. Feedback is always wel= come...