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_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,HTML_MESSAGE,MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: from minnie.tuhs.org (minnie.tuhs.org [IPv6:2600:3c01:e000:146::1]) by inbox.vuxu.org (Postfix) with ESMTP id D6F9C2178E for ; Mon, 20 May 2024 17:44:09 +0200 (CEST) Received: from minnie.tuhs.org (localhost [IPv6:::1]) by minnie.tuhs.org (Postfix) with ESMTP id A9AA143B36; Tue, 21 May 2024 01:44:05 +1000 (AEST) Received: from mail-pl1-x633.google.com (mail-pl1-x633.google.com [IPv6:2607:f8b0:4864:20::633]) by minnie.tuhs.org (Postfix) with ESMTPS id BB42443B35 for ; Tue, 21 May 2024 01:44:00 +1000 (AEST) Received: by mail-pl1-x633.google.com with SMTP id d9443c01a7336-1ee954e0aa6so47423745ad.3 for ; Mon, 20 May 2024 08:44:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1716219840; x=1716824640; 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=0KEhDC4k+KTziEjaSWKRVAHYOjScAnWp6AW0oM9Nld8=; b=EEzz5FstY9vlKaAdt4Mf9Vt3I0xltIHaT41KZVaDp5dtFakZqzaS5P01A5hH4gidsq /ejmxjR8TuUh3X/+e0PVQ3oH5pOEx65+/dnPwFoJ8IFGLm7gHAZHh3JMAwEw5V7mf/HT iHdiwydeffOR0mPUXnpDKY3hLwCcSaYDjG3pdch5fKDUfxR8cNTgj2CwXuG5xhPUhCGY +kxFb69JoDb3Kw8IleP1cVciiFmg0ATnlHN47o6JVG7WE88IBshqz9esKFp0ygk5x8RU 2B7H9fSEESq5gpjdW0Ct/cpm1nvxAeIG/Y/oigrUC/MeK8yEB7h+tTQGHHbEee8b8IWo cbPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1716219840; x=1716824640; 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=0KEhDC4k+KTziEjaSWKRVAHYOjScAnWp6AW0oM9Nld8=; b=wLqLNGOFL06J6HVs4RklLWrKhvO5iV4xqjMYGAtslqophlmapnUj+5xPZE+Ahj3sh0 07wzBJ57+cii6Dy7OxQnYZsO5hMZqJ/1F43QdAp6BJ2uzBDQl46s+HEtALCv1ylszijO lgMu1hy0HYBCM+awKcGZcXqYJCFv/wK4oNNs5uGU89IWPRqe2OsurZDs2HdmxmKJXmcl 3Ps3rr9hV0KLq7mqruF2Kt0oyD477uILjgVtisRn67YC3NeGrxzoNMyTjMjCTa9NnQa/ acP0nLj1UENfiyNvYGuSwhGTUGMZ1bK3sCEFWKI+Lx0Qc6HJ0wONQ0gFU2PEGv3JXo2y g6uw== X-Gm-Message-State: AOJu0YwQcTBn5ok0w2BGvgyTawcCASiEiFLjvF6XZ0GK+m4lD8ayr2by ORZRXuK5eK47XWtDojjof3e2nEdzGJaIb1VbIN8gojf2doRC2Rulpphp0GyRlyTJT/F2FmkMw9i ToICTEQsnbeyZAtlfogowoWKwTKdBKA== X-Google-Smtp-Source: AGHT+IH5XbDfXW2E0/vWMC7jEwrt0v6bJLkSZp2yG9HclzMg8ncE6ud5El5UVbsUgPvHxNHQ9QERAHA6h3Bwf9hP8/I= X-Received: by 2002:a05:6a20:244f:b0:1ad:1c9d:f682 with SMTP id adf61e73a8af0-1afde120e1fmr32751739637.35.1716219840023; Mon, 20 May 2024 08:44:00 -0700 (PDT) MIME-Version: 1.0 References: <20240518203319.3oAKtOSk@steffen%sdaoden.eu> In-Reply-To: From: Paul Winalski Date: Mon, 20 May 2024 11:43:49 -0400 Message-ID: To: Adam Thornton Content-Type: multipart/alternative; boundary="000000000000ebd4520618e4916c" Message-ID-Hash: V5YIA2KLHMJVS4JUXCPVAZBCWBZJR4KY X-Message-ID-Hash: V5YIA2KLHMJVS4JUXCPVAZBCWBZJR4KY X-MailFrom: paul.winalski@gmail.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: The Eunuchs Hysterical Society X-Mailman-Version: 3.3.6b1 Precedence: list Subject: [TUHS] Documentation (was 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: --000000000000ebd4520618e4916c Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Mon, May 20, 2024 at 2:08=E2=80=AFAM Adam Thornton = wrote: > I can't tell you--although some of you will know--what a delight it is to > be working on a project with an actual documentation engineer. > > That person (Jonathan Sick, if any of you want to hire him) has engineere= d > things such that it is easy to write good documentation for the projects = we > write, and not very onerous. > > Design for documentability, testability, and ease of maintenance are what distinguishes good software engineering from hackery. Back when I worked in DEC's software development tools group, we had professional technical writers who write the manuals and online help text. There was an unexpected (at least by me) benefit during a project's design phase, too. Documentation was written in parallel with the code, so once the user interface specification was arrived at, first order of business was to sit down with the tech writer and explain it to them. Sometimes in the process of doing that youd stop and think, "wait a minute--we don't really want it doing that". Or you'd find that you bhad difficulty articulating exactly how a particular feature behaves. That's a red flag that you've designed the feature to be too obscure and complex, or that there's something flat-out wrong with it. -Paul W. --000000000000ebd4520618e4916c Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Mon, May 20, 2024 at 2:08=E2=80=AFAM A= dam Thornton <athornton@gmail.com= > wrote:
I can't tell you--although= some of you will know--what a delight it is to be working on a project wit= h an actual documentation engineer.

That person (J= onathan Sick, if any of you want to hire him) has engineered things such th= at it is easy to write good documentation for the projects we write, and no= t very onerous.

Design for documentability= , testability, and ease of maintenance are what distinguishes good software= engineering from hackery.

Back when I worked = in DEC's software development tools group, we had professional technica= l writers who write the manuals and online help text.=C2=A0 There was an un= expected (at least by me) benefit during a project's design phase, too.= =C2=A0 Documentation was written in parallel with the code, so once the use= r interface specification was arrived at, first order of business was to si= t down with the tech writer and explain it to them.=C2=A0 Sometimes in the = process of doing that youd stop and think, "wait a minute--we don'= t really want it doing that".=C2=A0 Or you'd find that you bhad di= fficulty articulating exactly how a particular feature behaves.=C2=A0 That&= #39;s a red flag that you've designed the feature to be too obscure and= complex, or that there's something flat-out wrong with it.
<= br>
-Paul W.
--000000000000ebd4520618e4916c--