[Grok-doc] Future of the grok-doc list and community documentation in general

[Martijn Faassen]

Hey,

On Mon, Nov 16, 2009 at 7:48 PM, Steve Schmechel
<steveschmechel at yahoo.com> wrote:
> --- On Mon, 11/16/09, Martijn Faassen <faassen at startifact.com> wrote:
>> [snip]
>> > The other option would be for the Grok developers to
>> decide to make
>> > narrative documentation a priority, and bring a
>>
>> This won't magically fix the problem; the developers have
>> only a limited time too.

> I understand, but I have been in software development long enough to
> know that if a developer can say something is finished before the
> documentation is finished, the documentation will *never* be finished.
> (It is the same reason we insist on full test coverage before saying
> something is finished.)

Of course. But Grok does have official documentation which we make an
effort to maintain along with the code. More official documentation
will be good. We're after all not starting from scratch, so narrative
documentation will have to be written "after the fact". I (as a
developer) contributed the tutorial and the developer's notes. Others
contributed the reference and the documentation infrastructure in
general. I hope we can expand and improve what's there already,
eventually perhaps into something like a "grok book".

[snip traject]
> I know it is new, but how will someone find this code or its
> documentation without searching PyPI or reading the announcement in the
> grok-dev list?  If I search the Grok site or the Community Documentation
> site (still separate search indexes), I find nothing under "traject" or
> even "trails".  Shouldn't at least the "megrok.traject" package be
> referenced somewhere on the Grok site?

Good point. There's a lot of stuff I and others have written that
could use much better presentation on grok.zope.org, in fact. We need
to have more tutorials about libraries, and at least a bunch of links:
"interesting libraries you can try with Grok, and here is more info".
You could ask on grok-dev to see what should be on such a list.

[snip]
> Now once they have asked on the list and received help from current Grok
> developers, they may be willing to write up what they learned.  Some may
> be willing to go through all the time and effort involved with using the
> current Plone site to create a tutorial or how-to, and be on the hook to
> maintain it indefinitely.  Others will "cut and run" with what they
> learned.
>
> Maybe an easier contribution path along with some encouragement from
> those answering the questions would prompt more people to document the
> solution.  Maybe just adding a portion of the discussion to a page and
> adding the question to a FAQ with a link to the page.  At least the
> solution would be a little more visible and searchable than when it is
> buried in a discussion thread.

I think would be very good if we had a clear entry point that says:
"Want to contribute documentation? Do the following"
that explains in clear steps how to:

* how to contact the documentation people

* contribute to the plone site

* contribute to the official docs

A clear link on the Grok documentation page, or even on the home page,
would be a great step forward.

We have this now:
http://grok.zope.org/documentation/tutorial/contribute-to-the-grok-documentation

I don't think this is bad, but I think the contents of this could be
much improved to help to writing docs and contacting other docs people
in a "least effort" way.

>> It's easier with Repoze BFG as the project
>> and the documentation could grow at the same time, and
>> there's simply less to document.

> Agreed. But there seems to be a real commitment there to documenting
> things and treating lapses and mistakes in the documentation as
> seriously as errors in the code.  (Probably a reaction to past pains
> caused by poor documentation, but very handy for a new user exploring
> that framework's capabilities.)

Sure, and I'd like to have such an attitude for Grok, but again, we
have *huge* gaps in our documentation right now. I think we can fill a
lot of those gaps if we took the contributions on grok.zope.org and
organized them into a clear narrative. But we also have to document a
lot of underdocumented ZTK libraries which we build on. Luckily at
least the ZTK effort tries to drop the amount of libraries we need to
document, but we have a long way to go yet.

(by the way, our documentation could also be improved by putting in a
clear link to the ZTK, at leasf or 1.1)

>> How can we make life easier in the Plone context? Give a
>> lot of people approval rights in the workflow?

> Some ideas (off the top of my head) that could be incorporated into the
> current Grok site:  (I think some are already available in Plone, but
> are turned off for some reason.  Maybe a Grok-based Plone plug-in could
> be used to provide the rest along with a opportunity to document the
> building of that plug-in.)

[snip lots of ideas]

I'm in favor of any effort that makes it easier to contribute and
manage documentation. If that means switching to other software, so be
it. But in my experience switching to other software tends to bog down
in endless discussions and a lack of action unless someone just Does
It, and convinces someone of the benefits. So I don't want a lot of
technical discussions as they distract enormously from the actual work
of producing and maintaining documentation.

> Grok itself is not "batteries included", but you can use a dizzying
> array of other Zope/Python code with Grok.  It seems that sometime
> simple libraries are used in the documentation because they are easier
> to explain, but that might not be what actually gets used on a real
> project for a customer.  Some sort of guidance here is useful for the
> new developer.
>
> - Maintain an exhaustive list of available libraries and add-ons for
>  Grok.  (If you ever used it or think it could be used, then list it.)
>  This would list the name, a reference URL, and a short (1 to 3 sentence)
>  description of the ways it can be used.  Even if the library is not
>  available to others as open source, list its name.  That way, others can
>  see you made the choice in that situation to roll your own solution or
>  purchase one.  That is still a helpful bit of information.

Ah, yeah, this is the same idea as the one I had above. I think this
would be a good discussion to start on grok-dev so I've started it.

> - Allow the other developers to tag the list with additional
>  attributions that state something like, "<developer name> used this
>  library/add-on in <project name>"
>
> - Allow the other developers to rate items on this list based on ease of
>  use and available documentation.
>
> I know this ended up being a pretty big wish list, but if Grok is
> serious about attracting non-Zope users, someone has to help guide them
> through the vast forest of options, and give them an opportunity to
> contribute so they start to feel that they are a part of the community.
> Grok is definitely a key step in making this even possible, it just
> needs to be a little more approachable at the point of first contact.

I agree completely. But we need to find small steps that individual
volunteers can accomplish. Big wish lists may be intimidating and can
therefore block incremental progress.

That said, could you turn this wish list into a document somewhere
that's maintained by the documentation project and can be easily found
by potential contributors? That way people who *want* to contribute
get some ideas of what's interesting to us.

[snip]
> Now that the caveman is done smashing most ZCML, he needs to become a
> well spoken tour guide.

+1

Anyway, immediate points of action:

* investigate how to make the Plone site easier for documenters

* document better step by step guide on how to contribute to docs on
grok.zope.org.

* better capture documentation that gets created "in the field" and
either link to it on grok.zope.org or move it to grok.zope.org

* convert good candidates of documentation on grok.zope.org into
"official documentation" (I think this needs discussion on grok-dev as
the developers make a certain commitment to maintain this)

* document popular libraries used by developers in their own grok projects.

Regards,

Martijn