[Grok-dev] Pending removal of KSS-howtos, will they be missed?
sebastian at urbantalk.se
Wed Feb 17 08:31:58 EST 2010
You have some valid points!
However, I do have a mission statement for the grok-doc effort and
I'll stick to that one for now. I am worried that we will spend lots
of time discussing how to improve documentation and then have no time
or energy to actually improve it. :)
17 feb 2010 kl. 14.16 skrev 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
>> 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
> 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
> 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
> review would mean a lot of time/techniques to check, difficult to
> up to several reviewers) and might stop people from contributing new
> There is certainly a difference between adding a new doc (where you
> write whatever you like) and extending an existing one, which might
> already look carefully ordered, formulated and designed by others.
> _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
> to the overview/starting page and someone would have to look after
> Maybe there is another way one can go?
> From my view it would be nice if one could achieve both: the
> (for writers) to create short, quickly written howtos and the
> possibility (for readers) to get an overview over a certain topic
> 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)
> 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,
More information about the Grok-dev