Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kX3se-0006Pg-24 for pgsql-hackers@arkaria.postgresql.org; Mon, 26 Oct 2020 14:53:52 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1kX3sb-0006Sg-Mz for pgsql-hackers@arkaria.postgresql.org; Mon, 26 Oct 2020 14:53:49 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kX3sb-0006SZ-EW for pgsql-hackers@lists.postgresql.org; Mon, 26 Oct 2020 14:53:49 +0000 Received: from mail-pf1-x42f.google.com ([2607:f8b0:4864:20::42f]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1kX3sX-0005pn-O9 for pgsql-hackers@lists.postgresql.org; Mon, 26 Oct 2020 14:53:48 +0000 Received: by mail-pf1-x42f.google.com with SMTP id x13so6313276pfa.9 for ; Mon, 26 Oct 2020 07:53:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=qLsOidRKJfCyHANTyCR/RMfqdf505+ja+X41vr+eDHU=; b=pXjoLFmHdxvhbV235/rThYewsXSu912M5YfH8sTUOBqNlsRJzIJzQ6MyvB9JsY8eNm pVMLCTaR1Bu+6lWCI8G8eZcvlyfbd/l2waOfWYaC3HU1oZufzYgsqm3PQMHBAqQ327Il GITXRiIxnS3OcbD/LTF/XE9Iw7YoBMr4KlGtDA0E0QvwSTKfbfDh1InyXt+ddgn/rIw6 GkcfqNK4tyoA+DD2kZjT4UMLqnRVtNZfSdOz/l5jweHYgKwi0SjT2Dcq1oge/UQkoL7b 1rmAFKMe4kevUkJvxq0FfXJHT0WH5+t428Fw4Lucvm0vuqF7e8VzCE7kmPzMRFyy+IZb yfHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=qLsOidRKJfCyHANTyCR/RMfqdf505+ja+X41vr+eDHU=; b=PjZjfF0SH+vLwURrDRQkSK8go9v0phK3Zm1JFSbHH1KgBLBZTaQs8u5vtHOLzD7FwY oEPsyLqY+YVGy2jILSuCYxxlcMRugZXtoXBJGnwS9eTk52Q/mnfIFrRRE4szmTMaixc2 hfLsOAAExhEBdRw4thFiMCKX0teFsegWj8F9R3xU9fPUHkSyxHJdemy0D+rvQL5rLS97 xfKE1N9pofdZR7QHd3+xhpwL9ViRQ31y2zjzxgCYib00Hk9pTasBnn0oWYAUFv6wGjS/ 7waSZKF5LvJ6QDp3IRnevKftBSI3CXcxzllWEh9fvgXpdK6S3Q7TFHWgiqwon1SzSJGH MewA== X-Gm-Message-State: AOAM53155pWvA21sTDP183Qsm4SwUTJn3KXqsTQK7q27NcDxEevgBifQ yw57Xjr3A1FnsK7W9Whf9kwlC06eMeh/+2vS2DKjplqZ6Oo= X-Google-Smtp-Source: ABdhPJzFHKstxfLmgELgA6LeYEc1irlRS2gt/zYBTKCmmFIXloRpLgtKF+WnCFrucKa7GCtPV3j2Lfu58biVgAli2uk= X-Received: by 2002:a63:f343:: with SMTP id t3mr13655085pgj.86.1603724024368; Mon, 26 Oct 2020 07:53:44 -0700 (PDT) MIME-Version: 1.0 Received: by 2002:a17:90a:549:0:0:0:0 with HTTP; Mon, 26 Oct 2020 07:53:43 -0700 (PDT) In-Reply-To: References: <13c65997-9502-7671-1a7b-50e5d5093514@purtz.de> <40aca6b45b0da614b94c8ef86d89b70b@xs4all.nl> <4b8bdb3b-10a7-e541-18ff-6a556ce89cd1@purtz.de> <9df5b9c8-71fe-47a8-4670-346a0ae7e2cd@purtz.de> <567f7c92-dce9-7424-9022-54b31eb12740@purtz.de> <1B5F7D1E-B389-4D3B-973A-A8D183D8530A@yesql.se> <766cab17c6af48956558611520956b77@xs4all.nl> <93fd8e15-8639-23c8-c7c4-d4cfca323189@purtz.de> <32c7ebc0-f69f-8a77-c397-8fcb9139d8d3@purtz.de> From: "David G. Johnston" Date: Mon, 26 Oct 2020 07:53:43 -0700 Message-ID: Subject: Re: Additional Chapter for Tutorial To: =?UTF-8?Q?J=C3=BCrgen_Purtz?= Cc: PostgreSQL Hackers Content-Type: multipart/alternative; boundary="000000000000ca532705b2941868" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --000000000000ca532705b2941868 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Removing -docs as moderation won=E2=80=99t let me cross-post. On Monday, October 26, 2020, David G. Johnston wrote: > On Monday, October 26, 2020, J=C3=BCrgen Purtz wrote: > >> On 21.10.20 22:33, David G. Johnston wrote: >> >> >> Two, I find the amount of detail being provided here to be on the >> too-much side. A bit more judicious use of links into the appropriate >> detail chapters seems warranted. >> >> The patch is intended to give every interested person an overall >> impression of the chapter within its new position. Because it has moved >> from part 'Tutorial' to 'Internals' the text should be very accurate >> concerning technical issues - like all the other chapters in this part. = A >> tutorial chapter has a more superficial nature. >> > Haven=E2=80=99t reviewed the patches yet but... > > I still think that my comment applies even with the move to internals. > The value here is putting together a coherent narrative and making deeper > implementation details accessible. If those details are already covered > elsewhere in the documentation (not source code) links should be given > serious consideration. > > David J. > > --000000000000ca532705b2941868 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Removing -docs as moderation won=E2=80=99t let me cross-post.

On Mon= day, October 26, 2020, David G. Johnston <david.g.johnston@gmail.com> wrote:
On Monday, October 26, 2020, J=C3=BCrgen Purtz <juergen@purtz.de> wro= te:
=20 =20 =20
On 21.10.20 22:33, David G. Johnston wrote:

Two, I find the amount of detail being provided here to be on the too-much side.=C2=A0 A bit more judicious use of links into the appropriate detail chapters seems warranted.

The patch is intended to give every interested person= an overall impression of the chapter within its new position. Because it has moved from part 'Tutorial' to 'Internals' the text sh= ould be very accurate concerning technical issues - like all the other chapters in this part. A tutorial chapter has a more superficial nature.

Haven=E2=80=99t reviewed the patches yet but...
=

I still think that my comment applies even with the mov= e to internals.=C2=A0 The value here is putting together a coherent narrati= ve and making deeper implementation details accessible.=C2=A0 If those deta= ils are already covered elsewhere in the documentation (not source code) li= nks should be given serious consideration.

David J= .

--000000000000ca532705b2941868--