Re: [tao-discuss] [Gendispatch] Requests for IETF 114

[Jay Daley <[e-mail]>]

I hope you will all forgive the liberty but I’m going to repost a slightly edited version  of a message I sent to tao-discuss in April [1].  I’ve left off the bit about how content is reviewed by the community which, while relevant, is second order to this discussion:


# Structure of our content

We have a huge volume of content, written by many dedicated people over many years and there are a lot of positives in that:

- lots of people voluntarily put huge effort into writing documentation
- people keep an impressive array of knowledge in working memory that they can use both to author and review
- people really care and are trying hard to provide people with useful info
- great level of detail

However, much of our content is written for "IETF participants" in the broadest sense, rather than more targeted at specific roles or tasks and that creates a range of issues. In other words, our content often seems to assume that all participants are going to speak in WGs, author drafts, be a scribe, ask questions at the plenary, etc, etc. The issues are:

- our content often tries to cover everything that someone might possibly need to know, ever, 
- we say the same/similar thing in multiple places, which in turn makes it hard for people to find everything they need in one place
- reading and understanding our content is overwhelming, there’s rarely an easy way in
- leads to duplication as each of the locations tries to cover enough to be useful
- when things change the incorrect text has to be tracked down in multiple places, which it rarely is and so stale content abounds

What we need, and what Greg is working on with emodir, is a participant journey - a set of roles that participants take that we can flesh out and target our content at. To be clear, I don’t mean the difference between beginner and expert, those can still be interpreted as "need to know everything" just at different levels of detail. Instead I mean "roles" such as: mailing list lurker, in-person participant, author, wg chair, etc. The new authors.ietf.org and chairs.ietf.org follow that principle - they aggregate all the information for one specific role into one place. Those are not finished by any means, we don’t have a formal review team in place, there’s lots of old content around, we don’t have enough stratified content for beginners to experts, but they are getting there.

# Our style of writing

Most of our content, whoever the author, is written in a friendly open style. Authors have made a great effort to be clear and to be inclusive.

However, despite that, there are two bad habits that fly underneath the radar. The first is to be defensive - must do this, don’t do this, avoid that, watch out for this, and so on. It’s as if successful participation in the IETF is predicated on learning all the rules not to break and the specific processes that must be followed to the letter. The second is to believe that IETF memes or in-jokes have the same (or any) meaning outside the IETF as they do within. The "many fine lunches" example captures that perfectly - a completely meaningless phrase unless you’ve been part of the IETF for at least 10? years.

# Relating this all to the Tao

For me, the Tao incorporates both the best snd the worst of the above. The effort and dedication that has gone into it are deeply admirable, the breadth of content is excellent and the tone is very friendly.

The problems I have with it though are not minor. The name itself, ’Tao’, is a reference too far. Sure some of use have read "The Tao of Pooh" and get the allusion but for most people, it goes straight over their heads

More importantly though, I sincerely doubt that it is of any practical use to its intended audience - it’s far too sprawling, detailed and full of rules to be of use to a newcomer. To be quite candid, every time someone recommends to a newcomer that they read the Tao, I cringe. What it does do is provide a useful reference for long-term participants (where else are the dot colours documented) but that’s not the intended audience. It’s become more a series of authoritative statements that can be referenced/found individually than a flowing document.

While I admire the effort that has gone into the Tao, I think we need to move on from this style of documentation. Replacing it with several smaller documents/sites/pages would be much more useful: "Guide to the role and structure of the IETF", "Guide to participating in IETF working groups", "Guide to making the most of IETF meetings", and so on.


Jay


[1]  https://mailarchive.ietf.org/arch/msg/tao-discuss/H3EPqJTO1V7OJL3f4_UtBo8IhbM/

> On 7 Jun 2022, at 00:32, Salz, Rich <rsalz=[e-mail]> wrote:
> 
>>   As it happens, I drafted the original version of that page in 2013, and I 
>    believe this text has survived pretty much unchanged:
> 
>>   "The Tao of the IETF is a must read document. If you read nothing else, read this."
> 
>>   The basic question here, where there appears to be genuine disagreement, is whether we want that statement to remain true.
> 
> That's a pretty good summary of the disagreement.  But "if you read nothing else" -- does watching video's count?
> 
>>   Personally, I think it's good to have a single document for this material, and that it should be printable. 
> 
> I'd like to know why it is important for someone new to the IETF to know that the first meeting was at a company that no longer exists.
> 
> As for printable: this is not the Internet of 30 years ago. Video is commonplace.  What is missing from this playlist: https://www.youtube.com/playlist?list=PLC86T-6ZTP5hFWNekiZYEYwEqVWB-cwfr which runs a total of 20 minutes?
> 
> 
> 
> _______________________________________________
> tao-discuss mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/tao-discuss
> 

-- 
Jay Daley
IETF Executive Director
[e-mail]