> Software that inherently defies concise description is suspect on > its face. In all likelihood it was built by accumulation way beyond > the bounds of any organizing principles that the author(s) may have > had at the outset.
MDN (Mozilla Development Network) is probably the first offender that comes to mind: https://developer.mozilla.org/en-US/docs/Web/ Nothing about the site's organisation, structure, or even URLs makes any sense because it's been accumulated from so many sources over time, and I don't think most of the authors knew or cared how the data was organised underneath... they just wanted to get it online and documented. Unfortunately, MDN is very much the bible of web technologies, and I use it constantly every day. I find myself wishing the site was in man-page form, so I could just run man 3dom insertBefore ... instead of: https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore ... each time I forget the argument order. Granted, web technologies are such a vast (and frequently changing) area, but I bet if they replaced their wikis with man-pages, the content would be 100 times more accessible than it is now. /rant On Sun, 2 Dec 2018 at 01:27, Doug McIlroy <d...@cs.dartmouth.edu> wrote: > > > if you are interested in my perspective - scrap the HTML documentation > > and fix the manpage. The reference manual - i.e. the manpage - is > > really important: when you use some software regularly, you use the > > reference manual all your life. Catering to the experienced user > > > is most important because whoever is serious about using the software > > will become experienced sooner rather than later. So the reference > > manual (manpage) must be concise, precise, and correct. > ... > > This is not rocket science and nothing new - just do it... > > +10 > > Software that inherently defies concise description is suspect on > its face. In all likelihood it was built by accumulation way beyond > the bounds of any organizing principles that the author(s) may have > had at the outset. > > Doug > >
