Quantcast

Simplifying the documentation page

classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Simplifying the documentation page

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

rss.gif (958 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Sebastian Ware
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Peter Bengtsson
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

David Bain-5
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:

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



_______________________________________________
Grok-dev mailing list
[hidden email]
http://mail.zope.org/mailman/listinfo/grok-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
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:

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

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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Sebastian Ware
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Peter Bengtsson
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3


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
 


* Expand the Tutorials and how-tos so you don't have to click it to
see what they all are.

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.
 

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

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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Peter Bengtsson
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kevin Teague
In reply to this post by Kamon Ayeva-3
Good work on the improvements!

Kamon Ayeva-3 wrote
>
>
> * Expand the Tutorials and how-tos so you don't have to click it to
> see what they all are.
>

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.
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 :)
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kevin Teague
In reply to this post by Peter Bengtsson

Peter Bengtsson wrote
3. Why aren't we using the grok web mailing list?
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.

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
In reply to this post by Kevin Teague


On Fri, Jun 6, 2008 at 2:05 AM, Kevin Teague <[hidden email]> wrote:

Good work on the improvements!


Kamon Ayeva-3 wrote:
>
>>
>>
>> * Expand the Tutorials and how-tos so you don't have to click it to
>> see what they all are.
>>
>
> 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.
>

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)

Cool. Will look into these improvements later today.

Regards,
Kamon


_______________________________________________
Grok-dev mailing list
[hidden email]
http://mail.zope.org/mailman/listinfo/grok-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Kamon Ayeva-3
In reply to this post by Peter Bengtsson


On Fri, Jun 6, 2008 at 1:28 AM, Peter Bengtsson <[hidden email]> wrote:
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

I just did some changes.



3. Why aren't we using the grok web mailing list?

Right, for the next improvements we could do that, since there are now a few people monitoring that list.
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Martijn Faassen-2
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Re: Simplifying the documentation page

Kamon Ayeva-3


On Fri, Jun 6, 2008 at 4:51 PM, Martijn Faassen <[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.

-- Kamon


_______________________________________________
Grok-dev mailing list
[hidden email]
http://mail.zope.org/mailman/listinfo/grok-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate
star

Re: Simplifying the documentation page

Martijn Faassen-2
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
Loading...