> documentation is like sex, because when it's good it's very good, and even when it's bad it's a hell of a lot better than nothing.
Yes, but even bad sex can be improved. Even if it takes fifty bites of the cherry. On Sun, Apr 29, 2018 at 7:05 AM, Roger Stokes < [email protected]> wrote: > Well said, Ian. > > There is an old joke: documentation is like sex, because when it's good > it's very good, and even when it's bad it's a hell of a lot better than > nothing. > > > > > > > On 4/29/2018 1:55 AM, Ian Clark wrote: > >> AFAIK, the current set of addons is in reasonably good shape, if not >>> >> always properly documented. Are you aware of specific issues with them? >> >> It's how they're documented that concerns me. But without even a "how to >> proceed" message on loading – just nothing – the addon in question is by >> definition not in good shape. If you're directed to someone's house you've >> never visited, and the door's kicked in or nailed-up, do you expect to >> find >> the inside in reasonably good shape? >> >> Taking the side of a novice J-er, as usual, I'd have issues with over half >> of them. If I go in along the recommended route: >> http://code.jsoftware.com/wiki/Addons >> …I see a comprehensive listing of addons for which over half the links are >> red (=missing). (58 red, 51 blue, 4 black.) >> An even smaller proportion of addons have a lab. Failing which, is it too >> much to ask for a working sample invocation of the chief verb for every >> addon? If pacman showed this it would be miles more informative than the >> airy description it usually offers. >> >> I've been trying recently to explore our addons library, to fill the gaps >> in my knowledge and avoid reinventing the wheel. Without consistent >> documentation of the most basic sort, the task that faces me is herculean. >> >> Now I'm not a novice user, and I have powerful tools, so nothing much >> stops >> me for long. So please don't offer to hold my hand in individual cases. >> That misses the point. >> >> >> >> On Sat, Apr 28, 2018 at 1:47 PM, chris burke <[email protected]> >> wrote: >> >> AFAIK, the current set of addons is in reasonably good shape, if not >>> always >>> properly documented. Are you aware of specific issues with them? >>> >>> On Wed, Apr 25, 2018 at 3:27 PM, Ian Clark <[email protected]> >>> wrote: >>> >>> It might be nice to have a way of marking addons as broken, either >>>>> >>>> with a >>> >>>> todo/fixme note or maybe just a documented way of deleting them? >>>> >>>> I think that's a splendid idea. >>>> >>>> Whenever I engage with an addon I've never used before, it takes me far >>>> >>> too >>> >>>> long to conclude that it's derelict. To stop our treasury of addons >>>> degenerating into a midden, I'd welcome an accepted *easy* way of >>>> >>> alerting >>> >>>> the owner – or fellow-users – to broken code (i.e. not a full-blown bug >>>> tracker). >>>> >>>> Am I the only one? Are we going to do something about it? Are we going >>>> to >>>> finish what we start? >>>> >>>> What's the best/most obvious alert mechanism? …the Talk page of the >>>> >>> landing >>> >>>> page for the Addon in question at code.jsoftware.com/wiki/Addons >>>> <http://code.jsoftware.com/wiki/Addons/GitHub> ? This forum? Or >>>> >>> something >>> >>>> Github-based? (and hence over the vendor's horizon)? >>>> >>>> >>>> ---------------------------------------------------------------------- >>> For information about J forums see http://www.jsoftware.com/forums.htm >>> >>> ---------------------------------------------------------------------- >> For information about J forums see http://www.jsoftware.com/forums.htm >> >> > --- > This email has been checked for viruses by Avast antivirus software. > https://www.avast.com/antivirus > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
