[libvirt] [PATCH 1/5] docs: api_extension: Remove links to the stale example patches

[Erik Skultety]

On Thu, Aug 23, 2018 at 03:14:38PM +0100, Daniel P. Berrangé wrote:
> On Thu, Aug 23, 2018 at 03:55:16PM +0200, Peter Krempa wrote:
> > On Thu, Aug 23, 2018 at 15:46:30 +0200, Erik Skultety wrote:
> > > On Thu, Aug 23, 2018 at 10:50:30AM +0200, Peter Krempa wrote:
> > > > The pathches used as an example for the api_extension manual don't hold
> > >
> > > s/pathches/patches
> > >
> > > > up to the current standards any more. Carefully remove links and
> > > > mentions of the patches from the docs.
> > >
> > > While I understand the impetus for the change, I am personally not convinced
> > > that we want to get rid of practical examples as a means of reference to the
> > > text, it's like a product documentation without examples - "hardcore mode".
> >
> > Any example will always become obsolete. I find trying to update it to
> > be a waste of time.
>
> I think that is rather a self fullfilling prophecy.
>
> The example becomes obsolete because no one can be bothered to spend
> time updating it. This doesn't imply we shouldn't even try. IMHO it
> is largely a sign that our priorities are screwed up, and we should
> put more effort into non-code writing parts of the project.
>
> Creating a long term healthy & viable project needs more than just
> writing lots of code. Considering feature implementation alone,
> there needs to be unit testing of the work, integration testing of
> the bigger system, documentation of the APIs and/or knowledgebase
> tutorials showing usage. In fact actually writing the core functional
> code could arguably end up being quite a small part of the overall
> work on a feature.
>
> Feature work is only one part of the project's long term success
> though. Bringing onboard new contributors is a key factor, and having
> something more to say to novices than "go read the code" is important
> to smoothing their onramp. Teaching application developers & admins
> what we've provide and how to use it is also heavily neglected in
> most cases such that we have great features no one knows about or
> uses correctly.
>
> Unfortunately we've historically not been very good at much of this,
> being very tightly focused on just writing the core code. This has
> definitely harmed our success in many areas. For example application
> developers have frequently questioned what value libvirt adds because
> we've not done a good enough job of telling people what we have
> implemented, or how to use it correctly once it exists.
>
> > > The fact that we took a patch series from the list archives as a reference
> > > probably wasn't the best thing to do, I think we should instead come up with a
> > > dummy API exercising all the sections in the docs which will conform to our
> >
> > Even coding style will become obsolete. Just the fact that we started
> > using the autofree stuff will make many existing examples obsolete.
> >
> > > current standards and which we can update as we please. I know that's much more
> >
> > We don't even keep our coding style guidelines up to date most of the
> > time. Do you think this would be any different?
>
> This is a failure of our review process. In adding new code style rules,
> we should consider updating of examples as required part of the work.
> Reviewers should raise this if it isn't done. I'm as guilty of missing
> this as the next person, but we shouldn't give up otherwise we will just
> stagnate.
>
> IOW, lack of updated examples wrt autofree is a bug with the original
> autofree patch series we missed.

Right, but then again, we preferred converting the code base in batches.
Nevertheless, we can update the guidelines for sure.
Apart from that, couldn't agree more with what you wrote.

Erik