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

[Steve Schmechel]

--- 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.)

That is not to say all developers do that.  I just looked at the
documentation you provided for Traject and it is quite good.  It
explains why you would want to use it (or not use it) and gives many
examples of how to use it in a project.

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?

> Unless people are willing to become developers to help with
> the documentation,
> the documentation isn't going to rapidly improve. 
If people become "Grok developers" they will probably do so to write
more Grok code; not to document someone else's code.  The "code
consumers" are the ones that need the documentation.  It seems silly to
ask them to become a Grok developer to document the code they want to
use.  

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.

> 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.)

> 
> I don't think we should start rocking the boat technically
> too much at
> this point. It risks scattering the documentation all over
> the place.
> The community documentation to me looks a lot better than
> one would
> find in the average wiki. (and I have no reason to suppose
> a wiki
> would be more than average in our case).
> 
> 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.)

Authors 
------- 
- See Change history of documents (preferably with a diff option) 
- Undo changes by recalling earlier version.  
- Manage comments (When a comment is incorporated into the document,
  remove after X days.)
- See "views per day" and "total views" history for their pages.  (It is
  nice to know people are reading what you wrote.)

Users 
----- 
- Rate documentation for helpfulness. (like Google Help or Amazon)
- Filter or sort documentation by rating or most viewed.  
- See Change history of documents (preferably with a diff option) 
- See document source of existing pages (read only) to help those who
  would like to contribute by seeing how others added markup for tags,
  images, and references to their documents.  (Right now, only the 
  author or administrators can see the source text of a document.)

Admins 
------ 
- View user comments that have been placed on a document but never
  replied to by the author, and either forward them to someone or fix
  the documents and remove the comments.  If the comment is not about a
  problem but is just regarding the usefulness of the document (good
  or bad), add an appropriate rating to the document and remove the
  comment.

Core Developers 
--------------- 
Help share practical experience with new developers.

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.

- 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.

For many, that point involves browsing the documentation and thinking
about how Grok could help them in their endeavors.  Then they ease into
using it here and there, and eventually become proficient enough to
create documentation for others.  Even later, they reach some limit of
Grok and are ready to extend the code as a Grok developer.

I don't think anyone (besides maybe a veteran Zope2 developer) really
says "I wanted to learn all of Zope3, but it was too hard to understand
because of that darn ZCML.  Now Grok is here and I think I will jump in
head-first and see if it is as wonderful as they claim."  Rather, I
think it is more a progression of small successes that slowly assimilate
them into the community.

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

Regards,
Steve