Subject: [tao-discuss] Glitches in Tao of the IETF Revision

From: Stuart Cheshire <[email-masked]>
Date: Mon, 15 Apr 2019 18:10:50 -0700

This weekend I reviewed “Tao of the IETF - Possible Revision”

<https://www.ietf.org/about/participate/tao/tao-possible-revision/>

I think this is a great improvement over the existing document, and should be made official as soon as possible. The current version is seven years old now, and some important things have changed in that time. Also, some attitudes have changed too, and the new wording reflects this appropriately:

attendance → participation
novices → newcomers
http → https

The new revision remains light-hearted, but omits some of the excessively frivolous text from the 2012 version. Some of those inside jokes were arguably funny, but inside jokes are precisely what is *not* salient to a newcomer.

I did notice a few glitches:

Sometimes the web page appears blank. Start with a wide web browser window, as wide as your screen allows, blank. Then open <https://www.ietf.org/about/participate/tao/tao-possible-revision/>. if your window is wide enough you should see the little table of floating links top right. Now make the web browser window narrower until the little table of floating links disappears. The entire page content disappears with it, and the entire top half of the scrollable page content area becomes blank space.

There are several places where the text switches to monospaced font. Is this intentional?

There are several places where “a href” tags appear in the text, e.g.:

> A good summary of this can be found in the aptly titled <a href="https://tools.ietf.org/html/rfc1796">RFC 1796</a>, "Not All RFCs Are Standards”.

In the Table of Contents all the main section numbers are off by one. And I don’t think the Table of Contents itself needs to be entry number 1 in the Table of Contents (which I think is the cause of them being off by one).

The main section heading numbering in the body text is messed up. For example:

12. Introduction (Should be section 1)

All the other main section heading numbers in the body text, that should be 2, 3, 4, 5, etc., all appear with number “1”.

There are a few other minor spelling and grammar typos I noticed. If this document lives in a Git repository or similar, let me know and I’m happy to contribute a Git pull request with my suggested fixes.

Stuart Cheshire

---

From: Niels ten Oever <[email-masked]>
Date: Tue, 16 Apr 2019 09:48:46 +0800

Hi Stuart, 

Thanks a lot for your comments, this version is now under IESG review, but I am sure that if you make a pull request they will include that in their review:

https://github.com/nllz/Tao-of-the-IETF/blob/master/Tao.md

Any XML magic to fix the numbering and auto-generate the Table of Content would also be very much appreciated. 

All the best, 

Niels

On Apr 16, 2019, 09:11, at 09:11, Stuart Cheshire <cheshire=[email-masked]> wrote:
>I think this is a great improvement over the existing document, and
>should be made official as soon as possible. The current version is
>seven years old now, and some important things have changed in that
>time. Also, some attitudes have changed too, and the new wording
>reflects this appropriately:
>
>The new revision remains light-hearted, but omits some of the
>excessively frivolous text from the 2012 version. Some of those inside
>jokes were arguably funny, but inside jokes are precisely what is *not*
>salient to a newcomer.
>
>Sometimes the web page appears blank. Start with a wide web browser
>window, as wide as your screen allows, blank. Then open
><https://www.ietf.org/about/participate/tao/tao-possible-revision/>. if
>your window is wide enough you should see the little table of floating
>links top right. Now make the web browser window narrower until the
>little table of floating links disappears. The entire page content
>disappears with it, and the entire top half of the scrollable page
>content area becomes blank space.
>
>> A good summary of this can be found in the aptly titled <a
>href="https://tools.ietf.org/html/rfc1796">RFC 1796</a>, "Not All RFCs
>Are Standards”.
>
>In the Table of Contents all the main section numbers are off by one.
>And I don’t think the Table of Contents itself needs to be entry number
>1 in the Table of Contents (which I think is the cause of them being
>off by one).
>
>All the other main section heading numbers in the body text, that
>should be 2, 3, 4, 5, etc., all appear with number “1”.
>
>There are a few other minor spelling and grammar typos I noticed. If
>this document lives in a Git repository or similar, let me know and I’m
>happy to contribute a Git pull request with my suggested fixes.
>
>Stuart Cheshire
>
>_______________________________________________
>tao-discuss mailing list
>[email-masked]
>https://www.ietf.org/mailman/listinfo/tao-discuss

---

From: Robert Sparks <[email-masked]>
Date: Tue, 16 Apr 2019 10:17:58 -0500

One comment inline:

> Sometimes the web page appears blank. Start with a wide web browser window, as wide as your screen allows, blank. Then open <https://www.ietf.org/about/participate/tao/tao-possible-revision/>. if y…

I confirmed this. It looks like a javascript bug to me. Note that the 
content is still there, it's just _way_ down the page. If you hit 
reload, layout computes more sanely. Other pages that have right side 
navigation content suffer the same problem. Fortunately, an initial load 
on a small device appears to do the right thing.