|
I find the documentation page a bit difficult to grasp. Lot's of
subheaders that "hide" the content, I would suggest turning some of them into bullets and removing the searchform (it is after all not much more than a duplicate of the main search form): ** Documentation for Grok ** - The Grok Tutorial - Grok Developer's Notes * Browse Documentation By Topic * [The topics here...] Feed for all documentation * Contribute to the Documentation * Found something that's not documented? Learn how you can contribute to the Grok Documentation project . Mvh Sebastian _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
Sebastian Ware <[hidden email]> writes:
> I find the documentation page a bit difficult to grasp. Lot's of > subheaders that "hide" the content, I would suggest turning some of > them into bullets and removing the searchform... At this point, I think that listing all of the documents on one page would be the most reasonable. Right now people would have to make a dozen or more clicks just to see what documents we offer. -- Brandon Craig Rhodes [hidden email] http://rhodesmill.org/brandon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
I agree. Adding the link
-Show all tutorials and howtos on one page would be great. But I wouldn't want to replace the current page. I think the current page just needs to be simplified. Mvh Sebastian 29 maj 2008 kl. 13.21 skrev Brandon Craig Rhodes: > Sebastian Ware <[hidden email]> writes: > >> I find the documentation page a bit difficult to grasp. Lot's of >> subheaders that "hide" the content, I would suggest turning some of >> them into bullets and removing the searchform... > > At this point, I think that listing all of the documents on one page > would be the most reasonable. Right now people would have to make a > dozen or more clicks just to see what documents we offer. > > -- > Brandon Craig Rhodes [hidden email] http://rhodesmill.org/brandon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Sebastian Ware
I don't mind there being plenty of things on the page.
What I do mind strongly is the excess that just adds noise. For example: The Grok Developer's Notes -------------------------------------------- Learn more about the framework internals and APIs with the _Grok Developer's Notes_. Could be replaced by: _The Grok Developer's Notes_ Or another alternative, replace: The Grok Tutorial --------------------------- Brand new to Grok? The Grok Tutorial is place to start learning about Grok. With this:: _The Grok Tutorial_ - the place to start learning how to Grok Basically, all the excessive headlines don't add any value. Like, do you really need to add an explanation after the big headline "Search the documenation"?? In fact, just a long input box followed by a button that says "Search the documenation" would be equally, if not better, user friendly and just much much less noise. 2008/5/29 Sebastian Ware <[hidden email]>: > I find the documentation page a bit difficult to grasp. Lot's of subheaders > that "hide" the content, I would suggest turning some of them into bullets > and removing the searchform (it is after all not much more than a duplicate > of the main search form): > > ** Documentation for Grok ** > > - The Grok Tutorial > > - Grok Developer's Notes > > > > * Browse Documentation By Topic * > > [The topics here...] > > > Feed for all documentation > > > > * Contribute to the Documentation * > Found something that's not documented? Learn how you can contribute to the > Grok Documentation project . > > > Mvh Sebastian > > > _______________________________________________ > Grok-dev mailing list > [hidden email] > http://mail.zope.org/mailman/listinfo/grok-dev > > -- Peter Bengtsson, work www.fry-it.com home www.peterbe.com hobby www.issuetrackerproduct.com _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Sebastian Ware
Do everyone agree with simplifying the page along the lines of:
** Documentation for Grok ** o The Grok Tutorial o The Grok Developer's Notes o All tutorials and howtos * Browse Documentation By Topic * [The topics here...] ... +1 for me. I can work on it today so we can see the result. Cheers, Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
I like the idea of Job Roles and Checklists:
We could have a Grok Checklist based on your role Designer Checklist ----------------------------- This is what you need to know to be an effective designer with Grok: * CSS (learn CSS here.....) * HTML (learn HTML here ....) * ZPT ..... Developer Checklist ---------------------------------- This is what you need to know to be an effective designer with Grok (we've tried to put them into a sensible "learn-this-first" order): * CSS * HTML * ZPT * Viewlets (learn viewlets first) * ........ * Subversion Deployment/System Integrator Checklist ------------------------------------------------------------- * Python Eggs * Buildout * Subversion * REST On Fri, May 30, 2008 at 9:58 AM, Kamon Ayeva <[hidden email]> wrote: Do everyone agree with simplifying the page along the lines of: _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Kamon Ayeva-3
On Fri, May 30, 2008 at 4:58 PM, Kamon Ayeva <[hidden email]> wrote: Do everyone agree with simplifying the page along the lines of: I think it's better to wait for monday before doing that anyway. -- Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
Hi all,
Regarding the Documentation section homepage... On Fri, May 30, 2008 at 6:18 PM, Kamon Ayeva <[hidden email]> wrote: I made a little template to mock up that (in portal_skins/custom), at least mostly.
The "Browse by topic..." part is commented out because I did not want to put effort in making the "view" code work. It is just to give an idea and see if people are ok to move to this presentation. If yes, I will commit the real code. Also, it would be made nicer when everything is in place, with a better CSS rule for the positioning of the search box. See http://grok.zope.org/documentation/new_doc_frontpage Cheers, Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
I suggest dropping the search box since it is only a duplicate of the
searchbox in the Grok navbar. I also miss the "Contribute" part that was under "Browse by topic", good to have many entry points for contribution. Other than that I think it is a great improvement. Mvh Sebastian 2 jun 2008 kl. 18.02 skrev Kamon Ayeva: > Hi all, > > Regarding the Documentation section homepage... > > On Fri, May 30, 2008 at 6:18 PM, Kamon Ayeva <[hidden email]> > wrote: > > On Fri, May 30, 2008 at 4:58 PM, Kamon Ayeva <[hidden email]> > wrote: > Do everyone agree with simplifying the page along the lines of: > > ** Documentation for Grok ** > > o The Grok Tutorial > > o The Grok Developer's Notes > > o All tutorials and howtos > > * Browse Documentation By Topic * > > [The topics here...] > > I made a little template to mock up that (in portal_skins/custom), > at least mostly. > The "Browse by topic..." part is commented out because I did not > want to put effort in making the "view" code work. > > It is just to give an idea and see if people are ok to move to this > presentation. If yes, I will commit the real code. > Also, it would be made nicer when everything is in place, with a > better CSS rule for the positioning of the search box. > > See http://grok.zope.org/documentation/new_doc_frontpage > > Cheers, > Kamon > > _______________________________________________ > Grok-dev mailing list > [hidden email] > http://mail.zope.org/mailman/listinfo/grok-dev _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Kamon Ayeva-3
* I agree with Sebastian, no need to duplicate the search box.
* Expand the Tutorials and how-tos so you don't have to click it to see what they all are. * I miss the RSS feed link for all the documentation. That one is incredibly valuable for people who been here before and want to see what new documentation is available datesorted. 2008/6/2 Kamon Ayeva <[hidden email]>: > Hi all, > > Regarding the Documentation section homepage... > > On Fri, May 30, 2008 at 6:18 PM, Kamon Ayeva <[hidden email]> wrote: >> >> On Fri, May 30, 2008 at 4:58 PM, Kamon Ayeva <[hidden email]> >> wrote: >>> >>> Do everyone agree with simplifying the page along the lines of: >>> >>> ** Documentation for Grok ** >>> >>> o The Grok Tutorial >>> >>> o The Grok Developer's Notes >>> >>> o All tutorials and howtos >>> >>> * Browse Documentation By Topic * >>> >>> [The topics here...] > > I made a little template to mock up that (in portal_skins/custom), at least > mostly. > The "Browse by topic..." part is commented out because I did not want to put > effort in making the "view" code work. > > It is just to give an idea and see if people are ok to move to this > presentation. If yes, I will commit the real code. > Also, it would be made nicer when everything is in place, with a better CSS > rule for the positioning of the search box. > > See http://grok.zope.org/documentation/new_doc_frontpage > > Cheers, > Kamon > > > _______________________________________________ > Grok-dev mailing list > [hidden email] > http://mail.zope.org/mailman/listinfo/grok-dev > > -- Peter Bengtsson, work www.fry-it.com home www.peterbe.com hobby www.issuetrackerproduct.com _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
On Tue, Jun 3, 2008 at 10:14 AM, Peter Bengtsson <[hidden email]> wrote:
* I agree with Sebastian, no need to duplicate the search box. Ok, this occured to me later. +1
Ok, I think that means overriding the search results template. If that is useful for any search results, then this is just something to do independently of the documentation/helpcenter.
It will not be removed. It is not showed in my mockup but it is indeed kept. I can commit these improvements tomorrow, so others would have time to suggest their minor adjustments/corrections. Cheers, Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
Update: Please look at http://grok.zope.org/documentation and let me know if we're fine with this simplified version.
I can improve things as we go. Regards, Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
I like it!
1. Can you place some more space between the 4 items in the top list to make it look like they're more apart. 2. The bottom headling plus text can be converted to just say: "Learn how you can _contribute to the Grok Documentation_ project" and perhaps make it a bit more prominent 3. Why aren't we using the grok web mailing list? 2008/6/5 Kamon Ayeva <[hidden email]>: > Update: Please look at http://grok.zope.org/documentation and let me know if > we're fine with this simplified version. > I can improve things as we go. > > Regards, > Kamon > > _______________________________________________ > Grok-dev mailing list > [hidden email] > http://mail.zope.org/mailman/listinfo/grok-dev > > -- Peter Bengtsson, work www.fry-it.com home www.peterbe.com hobby www.issuetrackerproduct.com _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Kamon Ayeva-3
Good work on the improvements!
I would create a custom search view for the documentation section. This way Documentation-specific search result can show fields specific to documentation such as Grok Version, Audience and Version. The phc_stats view in the PloneHelpCenter product implements something similar to this (http://grok.zope.org/documentation/stats). A tweak we should do for the documentation section is re-enable display of Creators/Contributors. I took out the default 'big head' Creators/Contributors in the HowTo and Tutorial Views when creating the site since it was looking gangly and out-of-place in the layout, but we should display this information at the top or bottom of a docuemntation page view. Bonus points if you can click on someones name in the docs section and see all content they have contributed to :) You can provide RSS feeds in Plone 3 by creating a Collection with the desired criteria. I've created a 'feeds' Folder at the top-level of the web site (with the 'Exclude from Navigation' turned on) that provides a feed for everything within /documentation/: http://grok.zope.org/feeds/community-documentation/RSS (maybe we still want to tweak this criteria a bit more) FYI, we also have a feed that tracks changes to all content on the site: feed://grok.zope.org/all-content-updates/RSS Using Collections for feeds is better than using a generic Search RSS feed because: * You can update the structure of the web site, and update the Collections to reflect the new strucutre. Existing feeds will still work as intended, while generic Search RSS feeds will no longer work as expected. * Shorter, prettier URLs :) |
|
In reply to this post by Peter Bengtsson
See Martijn's reply in the another recent thread about wanting to keep as much Grok-related discussion in one place. e.g. if we have a grok-dev and grok-web and someone asks something documentation related on grok-dev we don't want to ignore that message because the doc/web people are on that list. Although I am really missing the lack of "No, you've posted on the wrong list. You want to post on the grok-*** list, dummy!" replies on the grok-dev list though :P We did recently create a Grok Web Admin list, but this list is only for sysadmin-ish topics. e.g. server resources, unexpected outages, software updates, etc. We are only using for people who can ssh into the server and fix/update things. |
|
In reply to this post by Kevin Teague
On Fri, Jun 6, 2008 at 2:05 AM, Kevin Teague <[hidden email]> wrote:
Cool. Will look into these improvements later today. Regards, Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Peter Bengtsson
On Fri, Jun 6, 2008 at 1:28 AM, Peter Bengtsson <[hidden email]> wrote: Right, for the next improvements we could do that, since there are now a few people monitoring that list.I like it! I just did some changes.
And use the grok-dev for important announcements regarding the content/website. -- Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
In reply to this post by Peter Bengtsson
Hi there,
I like the changes to the documentation page. I'd suggest however to say 'The tutorial for beginners' instead of 'the tutorial for newbies', as 'beginners' is a better term. Regards, Martijn _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
On Fri, Jun 6, 2008 at 4:51 PM, Martijn Faassen <[hidden email]> wrote: Hi there, Ok. Fixed. -- Kamon _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
|
Kamon Ayeva wrote:
> > > On Fri, Jun 6, 2008 at 4:51 PM, Martijn Faassen <[hidden email] > <mailto:[hidden email]>> wrote: > > Hi there, > > I like the changes to the documentation page. I'd suggest however to > say 'The tutorial for beginners' instead of 'the tutorial for > newbies', as 'beginners' is a better term. > > > Ok. Fixed. > Thanks! I tried to fix it myself but couldn't find quickly there the page template was hidden. Regards, Martijn _______________________________________________ Grok-dev mailing list [hidden email] http://mail.zope.org/mailman/listinfo/grok-dev |
| Powered by Nabble | Edit this page |
