[Grok-dev] Pending removal of KSS-howtos, will they be missed?

[Uli Fouquet]

Hi there,

Souheil CHELFOUH wrote:
> If you ask me (which is not the case),

I'm sure that Sebastian (who made a good point here) appreciates input
from everybody. At least I do :-)

>  I'd answer :
> 1. We can rename the document
> 2. We can propose a JQuery + megrok.resource alternative in the same document
> 
> We could rename the documents containing "KSS" into "Ajax" and propose
> chapters with different approaches

As KSS is only one approach amongst others I think that sticking with
KSS in name is not bad. Furthermore we yet have no docs describing
different approaches, so that looking into 'the-one-and-only-AJAX doc'
could make people think this is the only way to do AJAX with Grok. I
blame myself for not having written something about the experiences with
awesome hurry.yui already.

Having 'chapters', however, would be great IMO. AJAX is a typical
problem where one gets aware that the collection of docs we have in
documentation (at least the howtos) is a bit unordered (like an
unordered pile of really interesting papers).

AFAICS there are at least two possibilities with PloneHelpCenter to fake
chapters:

1) turn howtos that belong together into one tutorial with chapters.

2) create 'folders' for documents belonging together and add an
   'overview' or 'introduction' document with 
   'make-this-a-starting-point' flag enabled. That should also be
   possible, shouldn't it?

   Howtos in such a folder then might link-back to the overview.

While only the first approach really reduces the amount of search
results, it has the disadvantage of being worse to maintain/review (each
review would mean a lot of time/techniques to check, difficult to split
up to several reviewers) and might stop people from contributing new
docs.

There is certainly a difference between adding a new doc (where you can
write whatever you like) and extending an existing one, which might
already look carefully ordered, formulated and designed by others. That
_might_ stop people from contributing, but I'm not a psychologist ;-)

The latter approach (2) would preserve the ability to create short
howtos, but it would mean more maintenance effort from the
ordering-perspective: all docs in a certain folder would need a backlink
to the overview/starting page and someone would have to look after that.

Maybe there is another way one can go?

From my view it would be nice if one could achieve both: the possibility
(for writers) to create short, quickly written howtos and the
possibility (for readers) to get an overview over a certain topic (like
AJAX and Grok). If I had to decide, I'd tend to support the latter
approach (which means more or less to do what Souheil proposes) because
documentation is for readers in the first place.

Deprecated docs could anyway be renamed so that you can at least see
from the linked title in search results whether it is worth clicking.
For example

  Adding AJAX to Grok with KSS

could be renamed to:

  Adding AJAX to Grok with KSS [Deprecated]

Specifically for KSS we could also bring some docs together. At least
'Using KSS actions on a view' could very well go into 'Adding AJAX to
Grok with KSS'. I'll look into this.

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20100217/d723467e/attachment-0001.bin