[Grok website] Proposal for an improved site navigation

[Kamon Ayeva-3]

Hello all,

At the Grokkerdam sprint, Fred and I have looked at the current site structure to see how it could be improved and incorporate the new Reference generated from the Grok subversion tree (thanks to the work done by Uli).

To start, we are proposing the following navigation:

1) Get Grok(ked)  [or Get Started]

• Installation
• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Releases
• Download or get Grok from svn
• Grok extensions

This is a new section we propose to add, and which should come first, to get people started with Grok.

2) About Grok

• Why Grok ?
• Features
• Component Architecture
• Projects using Grok
• Who is Grok ?

This is already existing. We just need to improve its content a bit, and maybe add the "Projects using Grok" page.

3) Documentation

• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Refence Manual (this links to HTML generated using Sphinx on the server)
• Howtos (PHC)
• Tutorials (PHC)

This is a reorganization of the current documentation section to include a link to the Reference (static html structure) that is going to be generated from Subversion,
as well as user-contributed howtos and tutorials. (Also see the other mail from Fred regarding the reference documentation workflow.)
We also think that the overview menu generated from the PHC - when you are in the current PHC - should be removed from the left column because it is very long and confusing.

3) Community

• Grok Mailing Lists & Forums
• IRC Channel / IRC Channel Log
• Grok Wiki
• Issue tracker

We would keep this existing part unchanged.

These changes could be done step by step with some planning and after checking they do not conflict with other changes/plans.
So your comments are welcome.

-- Fred & Kamon


_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Kevin Teague]

>
>
> 1) Get Grok(ked)  [or Get Started]
>
> • Installation
> • "Beginner" Tutorial (this is a direct link to the Tutorial in the  
> "Reference Manual")
> • Releases
> • Download or get Grok from svn
> • Grok extensions

Note that "Installation" and "Download" have quite a bit of overlap  
between them. Anytime I approach a project I am unfamiliar with, I  
look for "download" first - I would guess the trend is for most people  
to look for a "download" link first? From the download page one gets  
presented with the necessary install instructions (since you don't  
actually want to download Grok, but instead run grokproject and let  
buildout do the downloading ...).

>
> 3) Documentation
>
> • "Beginner" Tutorial (this is a direct link to the Tutorial in the  
> "Reference Manual")
> • Refence Manual (this links to HTML generated using Sphinx on the  
> server)
> • Howtos (PHC)
> • Tutorials (PHC)
>
> This is a reorganization of the current documentation section to  
> include a link to the Reference (static html structure) that is  
> going to be generated from Subversion,
> as well as user-contributed howtos and tutorials. (Also see the  
> other mail from Fred regarding the reference documentation workflow.)
> We also think that the overview menu generated from the PHC - when  
> you are in the current PHC - should be removed from the left column  
> because it is very long and confusing.
>

Hosting the offical grok docs (reference, tutorial, notes) as static  
sphinx docs is easy enough. The PHC overview menu will need to be  
adjusted to accomodate it - if you have a working buildout of the grok  
web site for developing on, you can modify the gzo.plonesmashtheme  
package (http://svn.zope.org/gzo.plonesmashtheme/)

gzo/plonesmashtheme/portlets/grokdoc.py and phc_grok.pt make up the  
Documentation portlet that gets presented on the web site. You can  
modify the existing 'phc_grok.pt' template to suit the new/improved  
navigation (feel free to just rip out the topic-based listing stuff if  
it's undesirable). We can't use the same Navigation portlet as the  
rest of the site, since that Portlet just displays content as it's  
structured within Plone. But if you put mirror the top level  
navigation elements statically in the documentation-navigation portlet  
that should be fine, it's not like we are changing the top-level  
navigation very often.

You can also modify gzo/plonesmashtheme/browser/dochome.pt which is  
the documentation home page template to reflect the new documentation  
structure.

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Kamon Ayeva-3]

On Fri, May 2, 2008 at 3:40 AM, Kevin Teague <kevin@...> wrote:

1) Get Grok(ked)  [or Get Started]

• Installation
• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Releases
• Download or get Grok from svn
• Grok extensions

Note that "Installation" and "Download" have quite a bit of overlap between them. Anytime I approach a project I am unfamiliar with, I look for "download" first - I would guess the trend is for most people to look for a "download" link first? From the download page one gets presented with the necessary install instructions (since you don't actually want to download Grok, but instead run grokproject and let buildout do the downloading ...).

Ok. I buy that.
So we get less links, like:

• Download (page will include details on the different ways of installing, including svn)
• "Beginner" Tutorial (direct link to the Tutorial in the "Reference Manual")
• Gok releases
• Grok extensions

3) Documentation

• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Refence Manual (this links to HTML generated using Sphinx on the server)
• Howtos (PHC)
• Tutorials (PHC)

This is a reorganization of the current documentation section to include a link to the Reference (static html structure) that is going to be generated from Subversion,
as well as user-contributed howtos and tutorials. (Also see the other mail from Fred regarding the reference documentation workflow.)
We also think that the overview menu generated from the PHC - when you are in the current PHC - should be removed from the left column because it is very long and confusing.

Hosting the offical grok docs (reference, tutorial, notes) as static sphinx docs is easy enough. The PHC overview menu will need to be adjusted to accomodate it - if you have a working buildout of the grok web site for developing on, you can modify the gzo.plonesmashtheme package (http://svn.zope.org/gzo.plonesmashtheme/)

gzo/plonesmashtheme/portlets/grokdoc.py and phc_grok.pt make up the Documentation portlet that gets presented on the web site. You can modify the existing 'phc_grok.pt' template to suit the new/improved navigation (feel free to just rip out the topic-based listing stuff if it's undesirable). We can't use the same Navigation portlet as the rest of the site, since that Portlet just displays content as it's structured within Plone. But if you put mirror the top level navigation elements statically in the documentation-navigation portlet that should be fine, it's not like we are changing the top-level navigation very often.

You can also modify gzo/plonesmashtheme/browser/dochome.pt which is the documentation home page template to reflect the new documentation structure.

Thanks for this information.


-- Kamon

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[David Bain-5]

+1 on the proposed revisions to the website.

On Fri, May 2, 2008 at 2:34 AM, Kamon Ayeva <kamon.ayeva@...> wrote:

On Fri, May 2, 2008 at 3:40 AM, Kevin Teague <kevin@...> wrote:

1) Get Grok(ked)  [or Get Started]

• Installation
• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Releases
• Download or get Grok from svn
• Grok extensions

Note that "Installation" and "Download" have quite a bit of overlap between them. Anytime I approach a project I am unfamiliar with, I look for "download" first - I would guess the trend is for most people to look for a "download" link first? From the download page one gets presented with the necessary install instructions (since you don't actually want to download Grok, but instead run grokproject and let buildout do the downloading ...).

Ok. I buy that.
So we get less links, like:

• Download (page will include details on the different ways of installing, including svn)
• "Beginner" Tutorial (direct link to the Tutorial in the "Reference Manual")
• Gok releases
• Grok extensions

3) Documentation

• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Refence Manual (this links to HTML generated using Sphinx on the server)
• Howtos (PHC)
• Tutorials (PHC)

This is a reorganization of the current documentation section to include a link to the Reference (static html structure) that is going to be generated from Subversion,
as well as user-contributed howtos and tutorials. (Also see the other mail from Fred regarding the reference documentation workflow.)
We also think that the overview menu generated from the PHC - when you are in the current PHC - should be removed from the left column because it is very long and confusing.

Hosting the offical grok docs (reference, tutorial, notes) as static sphinx docs is easy enough. The PHC overview menu will need to be adjusted to accomodate it - if you have a working buildout of the grok web site for developing on, you can modify the gzo.plonesmashtheme package (http://svn.zope.org/gzo.plonesmashtheme/)

gzo/plonesmashtheme/portlets/grokdoc.py and phc_grok.pt make up the Documentation portlet that gets presented on the web site. You can modify the existing 'phc_grok.pt' template to suit the new/improved navigation (feel free to just rip out the topic-based listing stuff if it's undesirable). We can't use the same Navigation portlet as the rest of the site, since that Portlet just displays content as it's structured within Plone. But if you put mirror the top level navigation elements statically in the documentation-navigation portlet that should be fine, it's not like we are changing the top-level navigation very often.

You can also modify gzo/plonesmashtheme/browser/dochome.pt which is the documentation home page template to reflect the new documentation structure.

Thanks for this information.


-- Kamon

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Kamon Ayeva-3]

Hi all,

Just to update you that Uli and I have just filed tickets for the tasks needed to be done on the website/docs improvement.

https://bugs.launchpad.net/grok-web/+bugs

I am volunteering to help on these first tasks in the coming weeks.

Cheers,
Kamon

On Fri, May 2, 2008 at 1:02 PM, David Bain <david.bain@...> wrote:

+1 on the proposed revisions to the website.

On Fri, May 2, 2008 at 2:34 AM, Kamon Ayeva <kamon.ayeva@...> wrote:

On Fri, May 2, 2008 at 3:40 AM, Kevin Teague <kevin@...> wrote:

1) Get Grok(ked)  [or Get Started]

• Installation
• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Releases
• Download or get Grok from svn
• Grok extensions

Note that "Installation" and "Download" have quite a bit of overlap between them. Anytime I approach a project I am unfamiliar with, I look for "download" first - I would guess the trend is for most people to look for a "download" link first? From the download page one gets presented with the necessary install instructions (since you don't actually want to download Grok, but instead run grokproject and let buildout do the downloading ...).

Ok. I buy that.
So we get less links, like:

• Download (page will include details on the different ways of installing, including svn)
• "Beginner" Tutorial (direct link to the Tutorial in the "Reference Manual")
• Gok releases
• Grok extensions

3) Documentation

• "Beginner" Tutorial (this is a direct link to the Tutorial in the "Reference Manual")
• Refence Manual (this links to HTML generated using Sphinx on the server)
• Howtos (PHC)
• Tutorials (PHC)

This is a reorganization of the current documentation section to include a link to the Reference (static html structure) that is going to be generated from Subversion,
as well as user-contributed howtos and tutorials. (Also see the other mail from Fred regarding the reference documentation workflow.)
We also think that the overview menu generated from the PHC - when you are in the current PHC - should be removed from the left column because it is very long and confusing.

Hosting the offical grok docs (reference, tutorial, notes) as static sphinx docs is easy enough. The PHC overview menu will need to be adjusted to accomodate it - if you have a working buildout of the grok web site for developing on, you can modify the gzo.plonesmashtheme package (http://svn.zope.org/gzo.plonesmashtheme/)

gzo/plonesmashtheme/portlets/grokdoc.py and phc_grok.pt make up the Documentation portlet that gets presented on the web site. You can modify the existing 'phc_grok.pt' template to suit the new/improved navigation (feel free to just rip out the topic-based listing stuff if it's undesirable). We can't use the same Navigation portlet as the rest of the site, since that Portlet just displays content as it's structured within Plone. But if you put mirror the top level navigation elements statically in the documentation-navigation portlet that should be fine, it's not like we are changing the top-level navigation very often.

You can also modify gzo/plonesmashtheme/browser/dochome.pt which is the documentation home page template to reflect the new documentation structure.

Thanks for this information.


-- Kamon

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev