Re: [tao-discuss] Review Request for Possible Revision of the Tao of the IETF

[Jay Daley <[e-mail]>]

This whole conversation seems very messy, reflecting an underlying mess around content.  Thanlfully, we have some strands coming together to produce a new strategy for our content, which will then provide the clarity to resolve discussions like this.  What follows is my analysis of those strands and then how those relate to the Tao, starting with the less contentious issues first.  

#  Review

Review can mean a number of things.  It can mean that a document must be checked by a specific third party before it is published, which is how I think review of the Tao is being looked at, but it can also mean that content is open for anyone to review at any time, comment on and propose changes to.  For content that is going to be long-lived or small amounts of short-lived critical content then the former makes sense, but for large volumes of content that changes regularly the former becomes impossible and we have to use the latter.  The website content is clearly of that nature.  Enabling this latter kind of review requires some work:

- content published in a form/mechanism that allows for that "drive by" review and change requests, which we generally take to be GitHub.
- clear responsibilities on who reviews the change requests
- quick response to any issues and change request received   

We’ve partly achieved that for the two micro-sites we’ve recently launched - authors.ietf.org and chairs.ietf.org as those are now GitHub backed but the main website is not there yet.

#  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 from this conversation 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 

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