Re: REST API docs

[Patrick Williams <patrick@stwcx.xyz>]

[-- Attachment #1: Type: text/plain, Size: 2660 bytes --]

On Thu, Aug 03, 2017 at 10:22:26AM +1000, Benjamin Herrenschmidt wrote:
> On Wed, 2017-08-02 at 08:01 -0500, Patrick Williams wrote:
> > he documentation should be updated.  As I said, I've been
> > pointing out new interfaces being available (with an implementation) in
> > tag messages.  There are on the order of 500 commits going in every
> > month.  It really isn't possible for me to know which ones someone on
> > the mailing list might be interested in.
> > 
> > As we've said since the beginning of the 2.0 stream, all work is being
> > tracked on github.  You can see every feature being worked on and see
> > exactly when it closes due to the code being merged.  I get that Linux
> > has amazing announcements and wikis for each release, like
> > kernelnewbies, but those aren't done by Linus himself and I certainly
> > don't have the bandwidth do it.
> 
> Nobody has the bandwidth.
> 
> What you are saying is "if you use the project, you have to read and
> track every commit message for breadcrumbs of documentation because we
> aren't goin to keep the docs up to date".
> 
> This is just wrong and impossible for your users.
> 
> Ben.

Ben,

That is not what I wrote at all.  What I tried to write was this:

   * I've been attempting to point out high importance features in the
     release notes for the tags.

   * There seems to still be complaints about this being insufficient.

   * I cannot write the equivalent of LinuxNewbies for each tag, giving
     a paragraph for each commit.  No one else has volunteered to do
     this either.

   * I cannot know a priori when I have failed to sufficiently point out
     a change that might interest someone in a sufficiently obvious and
     detailed way.

Do you have any guidelines to help me out here on what is significant
enough to write a better "announcement" of and how detailed it needs to
be?  I'm obviously failing and I don't have any clear advise other than
"this is a particular instance when we wanted to know more details."

What Stewart does for skiboot is great and I respect the effort he puts
into these:

   * https://lists.ozlabs.org/pipermail/skiboot/2017-July/008067.html

What he does here, to the best of my reading, is to write a paragraph
for nearly each commit sequence he merges.  Again, this is great.  I do
not have the availability to do this.  If someone would like to help
out, I'm all for it.

I will warn that we have on the order of 150 commits per 2 week sprint
spread across about two dozen repositories.  This would be a pretty
significant undertaking for anyone.

-- 
Patrick Williams

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]