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

[Sebastian Ware]

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

Mvh Sebastian

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