<html>
  <head>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <p>Complexity is entropy. It occurs naturally in all human endeavor.
      It takes work to keep things small, orderly, and rational. But
      there is also a point where although a tool may be perfect in its
      conception and execution, from its own perspective, it is not as
      useful as a slightly more disorderly version that does what people
      want it to do. "Well they shouldn't want that !" is a common
      response. Then people write scripts to do for themselves what the
      tool doesn't do. Which might be right, but it might lead to a
      whole bunch of similar scripts to do the same thing, just a little
      differently And that's when we discover that it would have been
      better to have it in the one tool in the first place.<br>
    </p>
    So it's a back and forth, trial and error process. Eventually new
    balances get struck, and people of like minds and tastes find a new
    center, like Plan 9, or other things.<br>
    <br>
    Myself, I do tend to like tools that are smaller and more
    single-minded in their function (and that makes it possible to have
    documentation that is clearer and more concise), but as an example,
    sometimes I want the "-u" switch on diff, to make a patch, sometimes
    I don't, the default display is better for a quick review (but I
    think or expect that the essential diff engine is being shared).
    It's all a matter of judgment, but you can't apply good judgment
    until you have the experience gained from trying several
    alternatives. So things will get bloated up, and then they will need
    to be pruned and re-engineered, but hopefully we don't throw out the
    most helpful exceptions to the rule just because they don't fit with
    some sort of consistency aesthetic.<br>
    <br>
    <div class="moz-cite-prefix">On 05/18/2024 11:52 AM, Clem Cole
      wrote:<br>
    </div>
    <blockquote
cite="mid:CAC20D2NbHEdxKU6HA_ZQWYmc-HGhLE+F4e8XFoWePToRBP4-9Q@mail.gmail.com"
      type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div class="gmail_default"
            style="font-family:arial,helvetica,sans-serif"><br>
          </div>
        </div>
        <br>
        <div class="gmail_quote">
          <div dir="ltr" class="gmail_attr">On Sat, May 18, 2024 at
            2:18 PM Larry McVoy <<a moz-do-not-send="true"
              href="mailto:lm@mcvoy.com">lm@mcvoy.com</a>> wrote:<br>
          </div>
          <blockquote class="gmail_quote" style="margin:0px 0px 0px
            0.8ex;border-left:1px solid
            rgb(204,204,204);padding-left:1ex">But I'm ok with a terse
            man page with a SEE ALSO that<span class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"> </span>points
            to a user guide.<br>
          </blockquote>
          <div><font color="#0000ff">Only if the SEE ALSO has more
              complete and relevant information - otherwise, it degrades
              to VMS's famous "see figure 1" SPR.</font> </div>
          <blockquote class="gmail_quote" style="margin:0px 0px 0px
            0.8ex;border-left:1px solid
            rgb(204,204,204);padding-left:1ex">
            <br>
            Docs should be helpful.<br>
          </blockquote>
          <div><font color="#0000ff"><span class="gmail_default"
                style="font-family:arial,helvetica,sans-serif">And easy
                to extract information.</span> </font></div>
          <div><font color="#0000ff"><br>
            </font></div>
          <div><span class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"><font
                color="#0000ff">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:</font></span></div>
          <div>
            <ol>
              <li><span
                  style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">Full
                  manuals explain how something is built and it </span>it used<span
style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">.  It
                  helps to have theory/principles of operations behind
                  it and enough detail when done, you can understand why
                  and how<span class="gmail_default"
                    style="font-family:arial,helvetica,sans-serif"> to
                    use it.</span><span class="gmail_default"
                    style="font-family:arial,helvetica,sans-serif"></span></span><br>
              </li>
              <li><span
                  style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">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.</span></li>
              <li><font color="#0000ff">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<span
                    class="gmail_default"
                    style="font-family:arial,helvetica,sans-serif">.</span></font></li>
            </ol>
          </div>
          <div><span class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"><font
                color="#0000ff"><br>
              </font></span></div>
          <div>
            <div class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"><font
                color="#0000ff">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.</font></div>
            <div class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"><font
                color="#0000ff"><br>
              </font></div>
            <div class="gmail_default"
              style="font-family:arial,helvetica,sans-serif"><font
                color="#0000ff">Tutorials and reference pages are
                supposed to easy helpful things -- but often miss the
                mark for the audience.  </font><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif">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 </font><font
                style="font-family:Arial,Helvetica,sans-serif"
                color="#0000ff">built<font face="arial, helvetica,
                  sans-serif"> </font></font><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif">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</font><font
                style="font-family:Arial,Helvetica,sans-serif"
                color="#0000ff"><font face="arial, helvetica,
                  sans-serif"> </font>reference</font><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif"> 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.</font><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif">  </font></div>
            <div class="gmail_default" style=""><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif"><br>
              </font></div>
            <div class="gmail_default" style=""><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif">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.</font><br>
            </div>
            <div class="gmail_default" style=""><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif"><br>
              </font></div>
            <div class="gmail_default" style=""><font color="#0000ff"><font
                  style="" face="arial, helvetica, sans-serif">So Larry
                  -- I agree with you ... "</font><i>Docs should be
                  helpful</i>," but I fear saying like that is a bit
                like the Faber College Motto/Founder's Quote: "<i>Knowledge
                  is good</i>."</font></div>
            <div class="gmail_default" style=""><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif"><br>
              </font></div>
            <div class="gmail_default" style=""><font
                style="color:rgb(0,0,255)" face="arial, helvetica,
                sans-serif"><br>
              </font></div>
            <br>
          </div>
        </div>
      </div>
      <div hspace="streak-pt-mark" style="max-height:1px"><img
          moz-do-not-send="true" alt=""
          style="width:0px;max-height:0px;overflow:hidden"
src="https://mailfoogae.appspot.com/t?sender=aY2xlbWNAY2NjLmNvbQ%3D%3D&type=zerocontent&guid=15f365c0-9308-4b29-b13c-6b3d6d0d42df"><font
          color="#ffffff" size="1">ᐧ</font></div>
    </blockquote>
    <br>
  </body>
</html>