[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

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

IOW, lack of updated examples wrt autofree is a bug with the original
autofree patch series we missed.

|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]