Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

[Jesper Dangaard Brouer]

On Tue, 7 Feb 2017 14:23:23 -0700
Jonathan Corbet <corbet@xxxxxxx> wrote:

> On Tue, 7 Feb 2017 21:51:49 +0100
> Jesper Dangaard Brouer <brouer@xxxxxxxxxx> wrote:
> 
> > I sounds like Daniel (see other email) have bigger plans for what
> > Documentation/BPF/ should contain.  E.g. consolidating
> > Documentation/networking/filter.txt which covers the cBPF/eBPF internals.
> > If that is the case (and I like the idea), then it goes beyond a
> > "userspace-guide".  And perhaps "BPF" is a "book" of its own?  
> 
> One of the real problems with the kernel's documentation is that there is
> really almost no thought given to who the audience is.  We have docs for
> kernel developers, for system admins, for user-space developers, etc., and
> it's all mixed up into one big jumble.
> 
> An objective of mine in launching into this whole project is to try to fix
> that, so that people can readily find the documentation they need.  So I
> don't think a single top-level directory, with a mix of user-space API
> info and "internals", is the right direction to go.  The internals docs
> should, IMO, go elsewhere, probably in the core-api manual.
> 
> See what I'm getting at here?

First I was reluctant (as it would be "easier" just to cramp every eBPF
thing into one directory).  Thinking more about, I agree with you, and
I like your vision.  Focus on the target audience and avoid mixing
different target audience in the same document/book is the way forward.

My audience and objective is helping developers getting started using
eBPF, not core-developers on eBPF (like Daniel).  I do see that, if we
start mixing in too much "internals" then we loose sense of the
original target audience, and then they "exit" as they get "lost" in
details that does not concern them.

Separating BPF docs into different directories (or "books") will make
us think about the target audience.

I would like to propose directory structure:

 Documentation/user-guide/bpf/
 Documentation/core-api/bpf/


> > And it seems Daniel is proposing capital-letters BPF for the directory
> > name "Documentation/BPF/"?  Any opinions on that? (I'm neutral)  
> 
> I think we should paint it green; otherwise I'm not too concerned about
> this particular point...:)

True, bikeshedding...

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer