From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,HTML_FONT_LOW_CONTRAST,HTML_MESSAGE, MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: from minnie.tuhs.org (minnie.tuhs.org [50.116.15.146]) by inbox.vuxu.org (Postfix) with ESMTP id 0DBBF25B2F for ; Sat, 18 May 2024 20:52:53 +0200 (CEST) Received: from minnie.tuhs.org (localhost [IPv6:::1]) by minnie.tuhs.org (Postfix) with ESMTP id 5A2604365C; Sun, 19 May 2024 04:52:47 +1000 (AEST) Received: from mail-ua1-x936.google.com (mail-ua1-x936.google.com [IPv6:2607:f8b0:4864:20::936]) by minnie.tuhs.org (Postfix) with ESMTPS id EC40343654 for ; Sun, 19 May 2024 04:52:42 +1000 (AEST) Received: by mail-ua1-x936.google.com with SMTP id a1e0cc1a2514c-7f3ff632a51so933416241.1 for ; Sat, 18 May 2024 11:52:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ccc.com; s=google; t=1716058362; x=1716663162; darn=tuhs.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=04eEYOMYVX5myyK8DnyfluL2Xu9Q/BB/ftBNLMkcoYo=; b=EHBLcq8c0Ec8+7LVkPQWXvtABx0mCBIgSouMdSadYr/lG8SKMDgxWjMDcqix9Rl/eI UCknWkhi8DKxUqaF258tBwIRRu8nG5h4rbissn9rRt6SZPvT9zp5cUVxLS1+Rd3fgKO/ A62/4ksbC9kLBtcOnD46ODpWxRWy5+YHEyUq8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1716058362; x=1716663162; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=04eEYOMYVX5myyK8DnyfluL2Xu9Q/BB/ftBNLMkcoYo=; b=djsyVtjJlOoJJwhzQ0GunNqn9vWad0qMwt/7sd7+P+q2nvNHX7mRnhMztxykM7Dh06 sgRx7Ehm4+lNA+0KZqTzsVuKvHGu4x6mqWJLqa97bsK+/UrzUOrvxm7Bj6nCBqZoCWqH BUwrPFWFz/qmYRW0EHR6N/+4Kpi69AEtlmv6s8lNZyBkOANSurEA6nBQNcPrlhj5xrlG SwQydbds/3lY9JAlJX9CkzGhzPDR/7dkK5abhDBYhRXyQE/bCuT8pKQRLX6NEvyoCr/B gt8DJY/MlB5CwdHSAMdmnLp8+9oxfwzc3P9KEBG3shXK7RsWPjt0ayu6kM525HpoFVz7 R1TQ== X-Forwarded-Encrypted: i=1; AJvYcCUDr0T5+pGiOgdiC9nn3F+RN4pitojoNGJrfl+bM8df0BHEHa4nhTRurbBsVJBbR/YP7a9jAvFOyN3ngXqY X-Gm-Message-State: AOJu0Ywnof+26ZQE1tgmcRoJkYibqnoL9BNaq6/BIHJ1xm3vgVTUhaZu nI6OPoLqE6APdoq6gFXLYK1HGpIa4VS+FtlUSUpRk/AY2fzXQxE/DFFPGr3mV4HFUh0p9hX9ylA +RhW+CHxo5KNAawFIUAZ4Rz8bddfn+PlM7RtN X-Google-Smtp-Source: AGHT+IEeMULOiydhnnXWYuUQoN9Wl61GZZq8phAxnxOInyCQv7oZuFf9EfyvAEYrWdURalegEFeD5tTyXOka2zmSGR4= X-Received: by 2002:a05:6122:32d3:b0:4da:ae51:b755 with SMTP id 71dfb90a1353d-4e16d8e3507mr1706040e0c.3.1716058361960; Sat, 18 May 2024 11:52:41 -0700 (PDT) MIME-Version: 1.0 References: <20240518181825.GT9216@mcvoy.com> In-Reply-To: <20240518181825.GT9216@mcvoy.com> From: Clem Cole Date: Sat, 18 May 2024 14:52:05 -0400 Message-ID: To: Larry McVoy Content-Type: multipart/alternative; boundary="000000000000143bea0618bef940" Message-ID-Hash: ORMPUEVZQAMUHI5NRMYGFQVLQWSDLCMD X-Message-ID-Hash: ORMPUEVZQAMUHI5NRMYGFQVLQWSDLCMD X-MailFrom: clemc@ccc.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Douglas McIlroy , TUHS main list X-Mailman-Version: 3.3.6b1 Precedence: list Subject: [TUHS] Re: On Bloat and the Idea of Small Specialized Tools List-Id: The Unix Heritage Society mailing list Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --000000000000143bea0618bef940 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Sat, May 18, 2024 at 2:18=E2=80=AFPM Larry McVoy wrote: > But I'm ok with a terse man page with a SEE ALSO that points to a user > guide. > Only if the SEE ALSO has more complete and relevant information - otherwise, it degrades to VMS's famous "see figure 1" SPR. > > Docs should be helpful. > And easy to extract information. The issue to be comes back to the type of information each document is designed to give. I believe there at least three types of docs: 1. Full manuals explain how something is built and it it used. It helps to have theory/principles of operations behind it and enough detail when done, you can understand why and how to use it. 2. Tutorials are excellent for someone trying to learn a new tool. Less theory - and more -- examples, showing off the features and how to do something. 3. References pages - need to be quick look-ups to remind someone how to use something - particularly for tools you don't use every day/generally don't memorize. There are at least two more: an academic paper which might be looked at as a start of #1 and full books which take #1 to even more details. Some academic papers indeed are fine manuals, and I can also argue the "manual" for some tools like awk/sed or, for that matter, yacc(1) are full books. But the idea is the >>complete<< review here. Tutorials and reference pages are supposed to easy helpful things -- but often miss the mark for the audience. To me, the problem is the wrong type of information is put in each one and, more importantly, people's expectations from the document. I love properly built manual pages - I detest things like the VMS/TOPS help command or gnu info pages. What I really hate is when there is no manual, but they tell you see the HELP command -- but which command or "subtopic" -- Yikes. The traditional man system is simple quick reminders, basic reference and I can move on. For instance, I needed to remember which C library has the definition these days for some set of functions and what are its error return codes -- man 3 functions, I'm done. Tutorials are funny. For some people, what they want to learn the ideas behind a tool. Typically, I don't need that as much as how this toll does some function. For instance, Apple is forcing me the learn lldb because the traditional debuggers derived from UCB's DBX are not there. It's similar to different. The man page is useful only for the command lines switches. It turns out the commands are all really long, but they have abbreviations and can be aliases. I found references to this in an lldb tutorial - but the tutorial is written to teach people more how to use a debugger to debug there code, and less how this debugger maps into the traditional functions. Hey I would like to find an cheat sheet or a set of aliases that map DBX/GDB into it -- but so far I've found nothing. So Larry -- I agree with you ... "*Docs should be helpful*," but I fear saying like that is a bit like the Faber College Motto/Founder's Quote: "*Knowledge is good*." =E1=90=A7 --000000000000143bea0618bef940 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Sat, May 18, 2024 at 2:18= =E2=80=AFPM Larry McVoy <lm@mcvoy.com> wrote:
But= I'm ok with a terse man page with a SEE ALSO that=C2=A0poin= ts to a user guide.

Docs should be helpful.
An= d easy to extract information.=C2=A0

The issue to be= comes back to the type of information each document is designed to give. I= believe there at least three types of docs:
    Full manuals=C2=A0explain how something=C2=A0is built and it it=C2= =A0used.=C2=A0 It helps to have theory/principles of operations behind it an= d enough detail when done, you can understand why and how to use it.
  1. Tutorials are excellent for someone tryin= g to learn a new tool.=C2=A0 Less theory - and more -- examples, showing of= f the features and how to do something.
  2. References pages - need to be quick look-ups to remind someone=C2=A0how= to use something - particularly=C2=A0for tools you don't use every day= /generally=C2=A0don't memorize.
<= span class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-seri= f">
There are at least two more: an academic=C2=A0paper which might be = looked at as a start of #1 and full books which take #1 to even more detail= s.=C2=A0 Some academic papers indeed are fine manuals, and I can also argue= the "manual" for some tools like awk/sed or, for that matter, ya= cc(1) are full books.=C2=A0But the idea is the >>complete<< rev= iew here.

Tutorials and reference pages are supposed to easy helpfu= l things -- but often miss the mark for the audience.=C2=A0=C2=A0To me= , the problem is the wrong type of information is put in each one and, more= importantly, people's expectations from the document.=C2=A0 I love pro= perly built=C2=A0manual pages - I detest things like the VMS/TOPS help command or gnu inf= o pages. What I really hate is when there is no manual, but they tell you s= ee=C2=A0the=C2=A0HELP command -- but which command or "subtopic" = -- Yikes.=C2=A0 The=C2=A0traditional man=C2=A0system is simple quick remind= ers, basic referenc= e and I can move on.=C2=A0 For instance, I needed to remember which C = library has the definition these days for some set of functions and what ar= e its error return codes -- man 3 functions, I'm done.=C2=A0=C2=A0=

Tutorials are funny.=C2=A0 For some people, = what they want to learn the ideas behind a tool.=C2=A0 Typically, I don'= ;t need that as much as how this toll does some function.=C2=A0 =C2=A0For i= nstance, Apple is forcing me the learn lldb because the traditional debugge= rs derived from UCB's DBX are not there.=C2=A0 =C2=A0It's similar t= o different.=C2=A0 The man page is useful only for the command lines switch= es.=C2=A0 =C2=A0It turns out the commands are all really long, but they hav= e abbreviations=C2=A0and can be aliases.=C2=A0 I found references to this i= n an lldb tutorial - but the tutorial is written to teach people more how t= o use a debugger to debug there code, and less how this debugger maps into = the traditional functions.=C2=A0 Hey I would like to find an cheat sheet or= a set of aliases that map DBX/GDB into it -- but so far I've found not= hing.

So Larry -- I agree with you = ... "Docs should be helpful," but I fear saying lik= e that=C2=A0is a bit like the Faber College Motto/Founder's=C2=A0Quote:= "Knowledge is good."



--000000000000143bea0618bef940--