<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <p><font face="Gentium">Hello Mark,</font></p>
    <p><font face="Gentium">you are having a lot of useful suggestions.
        There are even more thoughts alike yours, regarding
        documentation. And indeed you are right that our documentation
        is kinda good as a reference manual but it kinda sucks if you
        are a newbie.</font></p>
    <p><font face="Gentium">The thing is, we have quite a long backlog
        and some technological debt to resolve (see e.g. multithreading
        or our still-non-existent API), and all of these are very
        time-consuming. Writing good documentation, or better to say,
        creating good paedagogical materials for self-learning, is
        time-consuming as well. And even though we are very much in
        favor of having better documentation, the aforementioned
        problems have somehow higher priority than documentation (money
        being the main reason).</font></p>
    <p><font face="Gentium">Anyway, I'll later try to split your
        suggestions into independent pieces and create our internal
        issues for each of them, to not lose them.<br>
      </font></p>
    <p><font face="Gentium">Now to the suggestions (inline):<br>
      </font></p>
    <p></p>
    <div class="moz-cite-prefix">On 2024-02-09 06:13, Mark Shuttleworth
      wrote:<br>
    </div>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <meta http-equiv="content-type" content="text/html; charset=UTF-8">
      <div dir="ltr">
        <div class="gmail_quote"><br>
          <div>Admittedly I am not a networking specialist, but perhaps
            that makes my feedback useful in terms of gaining new users
            and bringing Bird to a wider audience. My previous
            experience has been playing with Babel for this same
            personal project, and Bird is obviously a step up in
            complexity given its support for many different protocols.
            As an aside, it's great to see Babel support in Bird :)<br>
          </div>
        </div>
      </div>
    </blockquote>
    This is actually a very good position to read the docs and see what
    makes you confused. I'm very happy that you didn't freak out.<br>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <div dir="ltr">
        <div class="gmail_quote">
          <div><br>
          </div>
          <div>At the time, here's what I struggled with. Hopefully some
            of this will be helpful in shaping docs for new users.</div>
          <div><br>
          </div>
          <div>It would be useful early in the doc to have a
            visualisation of the relationship between a table such as
            master4 and a protocol, like kernel or ospf. I found drawing
            a picture for myself helped to make import vs export clear.
            Perhaps the docs can have a picture like that! My suggestion
            would be to make that visualisation include multiple
            protocols such as the kernel protocol and one of the routing
            protocols like RIP or OSPF, so that it can help explain how
            a route might move between routers (OSPF) and into the local
            machine routing table. I would walk through a full example,
            showing movement of routes in both directions from both
            protocols. Describe, step by step, how a kernel route would
            be learned and imported into a table like ipv4, and then
            exported by OSPF, and vice versa. Perhaps this is obvious to
            a routing expert but it wasn't obvious to me as someone
            playing with a proper routing daemon for the first time.</div>
        </div>
      </div>
    </blockquote>
    We indeed don't have many pictures in the documentation and we shall
    add some. Anyway, this reminds me of … you are a visual learner,
    more than a textual one, aren't you? Would you appreciate a video
    tutorial, explaining these things step by step?<br>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <div dir="ltr">
        <div class="gmail_quote">
          <div><br>
          </div>
          <div>The multi-protocol case (kernel protocol and ospf
            protocol) may be less interesting to someone who's focused
            on BGP or OSPF across many routers, but it seems to me to be
            critical to the new user experience. A new user is likely to
            have one, two or three routers, and they need to move routes
            between them AND get those routes installed into the kernel,
            so they have to understand the multi-protocol interaction
            dynamics. This is where things like preference, which are
            not things one can learn about just by reading about OSPF or
            RIP, come into play.<br>
          </div>
          <div><br>
          </div>
          <div>The part of the doc you refer to is critical - it covers
            the main deal which is 'which routes from the various
            protocols will move into position where they can be
            actioned', but it's also very terse, and it's just a
            paragraph or two in a long stretch of detail. It also uses
            the term 'preference' twice, and I'm not sure those two uses
            refer to the same thing. It says 'Preferences of the routes
            are compared' and 'Source protocol instance preferences are
            compared' but neither 'route preference' nor 'source
            protocol instance preference' has been defined before this
            text. I'm still not sure how I would go and look at a setup
            with birdc and find out easily what the route preference or
            source protocol instance preference would be.<br>
          </div>
          <div><br>
          </div>
          <div>So I think all of this warrants a section on its own,
            early in the overall documentation, that walks through the
            behaviours of protocols, channels, and tables, and how they
            interact. It's notable that other people have found a need
            to try and explain this more clearly themselves - digging
            around to compose this email I found another example at <a
              href="https://blog.kintone.io/entry/bird"
              moz-do-not-send="true" class="moz-txt-link-freetext">https://blog.kintone.io/entry/bird</a>
            which may be helpful to you.<br>
          </div>
        </div>
      </div>
    </blockquote>
    This probably needs much more rewriting, considering that there are
    also MPLS rules now, EVPN upcoming … good point from you. <br>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <div dir="ltr">
        <div class="gmail_quote">
          <div><br>
          </div>
          <div>It would also help if logging of decisions wrt import or
            export captured more of the rationale for the decision. As I
            dug into this I saw messages like 'route rejected by
            protocol', but no rationale for that rejection (it turned
            out to be the preference).  Because the relationship between
            tables and protocols, import and export is unclear
            initially, it would be helpful to be explicit in these log
            messages. Would it be possible to say something like this:</div>
          <div>
            <pre><i>  <TRACE> <a href="http://10.2.21.0/24"
            moz-do-not-send="true">10.2.21.0/24</a> from kernel import to master4 accepted
</i><i>  <TRACE> </i><i><a href="http://10.2.34.0/24"
            moz-do-not-send="true">10.2.34.0/24</a> from </i><i>master4 export to ospf1 rejected because protocol preference 100<30
</i></pre>
            In this example I'm replacing angle brackets with explicit
            import / export, and listing the table names explicitly, to
            try and make it easier for a new user to follow that log and
            not be confused. I'm trying to show direction in the order -
            from kernel import to master4, and from master4 export to
            ospf1. The reason for the rejection would help to then dig
            in to details like protocol preferences.</div>
        </div>
      </div>
    </blockquote>
    People actually quite often parse the logs so we don't have so much
    space to change the format, but you're right that the log format is
    very dense and sometimes misleading. Regarding the "because
    something" part … it's quite challenging to actually achieve this
    but I'll make an issue for it and we'll see later what can be done
    with that. Especially with the BIRD 3 multithreaded architecture,
    there may be some funny corner cases and race conditions which have
    to be checked for.<br>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <div dir="ltr">
        <div class="gmail_quote">
          <div><br>
          </div>
          <div>In debugging with birdc, I found the layouts rather
            inscrutable and could not find documentation. For example:</div>
          <div><br>
          </div>
          <div style="margin-left:40px"><span
              style="font-family:monospace">bird> show route </span></div>
          <div style="margin-left:40px"><span
              style="font-family:monospace">Table master4:<br>
            </span></div>
          <div style="margin-left:40px"><span
              style="font-family:monospace"><a href="http://0.0.0.0/0"
                moz-do-not-send="true">0.0.0.0/0</a>            unicast
              [ospf1 2024-01-31] * E2 (150/40/900) [192.168.12.2]<br>
              via 192.168.4.248 on bond-lan weight 1<br>
              via 192.168.4.249 on bond-lan weight 1<br>
              <a href="http://192.168.254.48/30" moz-do-not-send="true">192.168.254.48/30</a>
                 unicast [ospf1 2024-01-31] * I (150/40)
              [192.168.254.57]<br>
              via 192.168.4.248 on bond-lan weight 1<br>
              via 192.168.4.249 on bond-lan weight 1<br>
            </span></div>
          <div><br>
          </div>
          <div>What is each of those fields? It would be nice if the
            docs for the protocol also explained how birdc represents
            routes from that protocol. In this case, the docs at <a
href="https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.11"
              moz-do-not-send="true">https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.11</a>
            could show the various permutations of an OSPF route, and
            point out where preference and metrics are (it took a lot of
            googling to understand "E2 (150/40/900)" :)</div>
          <div><br>
          </div>
          <div>Similarly, while preference is a critical element of the
            table import / export route selection algorithm, it's hard
            to know what it actually is. For example, where is the
            preference of this protocol instance?<br>
          </div>
          <div><br>
          </div>
          <div><span style="font-family:monospace">bird> show ospf <br>
              ospf1:</span></div>
          <div><span style="font-family:monospace">RFC1583
              compatibility: disabled<br>
              Stub router: No<br>
              RT scheduler tick: 1<br>
              Number of areas: 1<br>
              Number of LSAs in DB: 32<br>
              Area: 0.0.0.0 (0) [BACKBONE]<br>
              Stub: No<br>
              NSSA: No<br>
              Transit: No<br>
              Number of interfaces: 3<br>
              Number of neighbors: 4<br>
              Number of adjacent neighbors: 4</span></div>
        </div>
      </div>
    </blockquote>
    <p>Documenting these is one solution (but you have to look it up),
      creating a web-browser-friendly interface is another one. (Both
      can be done.) And with our new shiny API (which is still mainly on
      the drawing board), the web-browser interface will be possible to
      create quite smoothly. Also, there are so-called looking-glasses,
      which are basically web interfaces over BIRD with added features.
      See e.g. Alice-LG: <a class="moz-txt-link-freetext" href="https://github.com/alice-lg/alice-lg">https://github.com/alice-lg/alice-lg</a></p>
    <p>With that, I'm quite convinced that we're gonna have some
      web-browser interface with all of the routes and parameters
      visualised, well styled and explained with context help. (Funding
      of such an effort, or even just getting a commercial support
      package to actually steer our development this way, would be very
      much appreciated, though.)<br>
    </p>
    <blockquote type="cite"
cite="mid:CAP3mdEDb4HdT+Esw7QXgKCny6buUvN8V=9wetDx6LWuaz=wGCw@mail.gmail.com">
      <div dir="ltr">
        <div class="gmail_quote"><br>
        </div>
        <div class="gmail_quote">Apologies if this is newbie stuff, and
          hopefully it helps you get your future newbies through that
          learning process faster with fewer questions to your list :)</div>
      </div>
    </blockquote>
    <p>You did the best thing you could, and thank you for all your
      thoughts. If you find any other suggestion, feel free to write it.</p>
    <p>Have a nice day!<br>
      Maria<br>
    </p>
    <pre class="moz-signature" cols="72">-- 
Maria Matejka (she/her) | BIRD Team Leader | CZ.NIC, z.s.p.o.</pre>
  </body>
</html>