Re: Drafting the documentation page

On 02/12/10 00:40, John Schinnerer wrote:
> Aloha,
>
>> Israel Saeta Pérez wrote:
>>>
>>> Hey,
>>>
>>> Nicolas Vasseur has been working on a cleaner plone.org/documentation
>>> page. Please check:
>>>
>>> http://plone.org/documentation/helpcenter_ploneorg2
>>>
>>> and tell us what you think. We want something clean and simple, pointing
>>> to our best manuals, as agreed before, and with links to other sections
>>> like the KB, error reference, faqs...
>>>
>>> Any comments appreciated!
>
> So far so good overall, I would say. Seems pretty obvious where to go
> for what, and there's not so much at once that it's overwhelming.
>
> The "by topic" sidebar is a good thing to have.
> And I would suggest put newest stuff first, oldest stuff last in what is
> displayed via those sidebar links.
> For example when I click on 'visual design' under 'Customizing Plone' in
> that sidebar, the second item displayed under "creating theme products"
> is "Creating a new theme for Plone: a real-world example (Plone 2.1,
> 2.5)". I suggest it ought to be down at the end of that section with the
> link to the old DIYPloneStyle 2.x item.
> In short, list Plone 4 and/or non-version-specific, and then 3.x, and
> then 2.x.
> Also, some indication as to what the gold stars next to an item mean.


I think that these lists of content are collections generated 
programatically, so we don't have too much control of the sorting. 
Showing the starred items first, then by date is an option, though. 
Would you agree with that?

Also, some elements show up at the same page in several different 
categories, which is wrong. I think that we should remove most 
categories and leave just "Installing and upgrading" (would cover also 
moving and buildouts config), "Customization" (would cover every 
customization that doesn't need coding) "Theming" and "Development" 
(would include i18n/l10n). This is just a suggestion. I think that the 
less topics the better, since people nowadays don't browse documentation 
by topic, but use Google to search by terms, which is much smarter.

Keywords (or Subjects) are also useless right now. I don't know if they 
show up or are used anywhere in any page in the documentation. :/  But 
they do not harm, so let's forget about them for now.


> For the main Documentation page a few more words of explanation under
> the link to "Theme reference" in the getting started section might be
> helpful to those new to Plone and its' terminology. Something drawn from
> this perhaps:
> "A theme is a collection of page templates, style sheets, components,
> and configuration settings that go to make up the individual look and
> feel of a Plone site" (the first sentence of "What's a Plone Theme?" page).


I've given the starting page another whirl, adding more descriptive 
descriptions and some introductory text ("Contribute" portlet). :)

Check it out at:
http://plone.org/documentation/helpcenter_ploneorg2

-- israel


------------------------------------------------------------------------------
Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
Tap into the largest installed PC base & get more eyes on your game by
optimizing for Intel(R) Graphics Technology. Get started today with the
Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs.
http://p.sf.net/sfu/intelisp-dev2dev
_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs