[FLOW3-general] Documentation - Structure, Location and Organisation in the FLOW3 ecosystem

[Jacob Floyd]

I don't like php.net comments. If blog-style comments are integrated, 
please provide a button, checkbox, or setting to let me keep them hidden (a 
setting in a cookie?). Keeping them in a separate talk page like wikipedia 
is nice, because its there when I need it, but it doesn't change things on 
the main documentation page. Plus, we've already got the Typo3 wiki to 
collaborate on documentation.

One of the issues I have with the comment feature, is I often look at the 
scrollbar to see how much documentation there is for me to read. That is 
impossible on php.net because of the massive comment storms that take 
forever to scroll through. If someone needs help, let them come to the 
newsgroup or IRC, not post a comment in the docs. If something needs to be 
changed or clarified in the docs, submit a change to the docs, don't just 
leave an errata-style comment on the page. At least, that's my philosophy 
with documentation: Keep the docs official, communicate about them 
elsewhere.

Cheers,
Jacob Floyd

On Saturday, April 28, 2012 4:26:13 PM UTC-6, Christian Müller (Kitsunet) 
wrote:
>
> On 27.04.2012 12:23, Franz Kugelmann wrote:
> > On 26.04.2012 18:42, Jacob Floyd wrote:
> >> On Wednesday, April 25, 2012 4:14:47 AM UTC-6, Franz Kugelmann wrote:
> >>>
> >>> Since it is planned to have a comment-functionality for the
> >>> documentation page, i guess we will have the cookbook-recipes as
> >>> comments there some day in the future.
> >>>
> >> Can you point me to the discussion about having a comment functionality?
> >> I'd like to understand the motivation for such a feature. Have any
> >> thoughts
> >> gone into designing this comment feature? Is it planned to be more like
> >> php.net doc comments, or more like Wikipedia with a separate talk page
> >> for
> >> each chapter/section? Why was this chosen?
> >
> > Hi Jacob,
> >
> > to be honest, i do not remember exactly, but we talked about it on the
> > developer days. I think Sebastian Kurfürst told me about this idea, but
> > we did not discuss it deeper.
> >
> > regards
> > Franz
>
> Hi all,
>
> the commenting was never "officially" discussed AFAIK.
>
> Instead we wanted to have that since quite some time already and the 
> Package for it is already in git we just need to bring everything 
> together. It is more a blog style commenting and I think if it goes the 
> same way as the PHP doc comments it would be nice.
>
> Cheers,
> Christian
> FLOW3 Core Team
>
> _______________________________________________
> FLOW3-general mailing list
> FLOW3-general at lists.typo3.org
> http://lists.typo3.org/cgi-bin/mailman/listinfo/flow3-general
>
>