TG2.1 documentation
pipoun
The TG 2.1 documentation is now highly ranked in a google search
result. For instance, it's in the first or second result for these
queries: "turbogears chameleon" "turbogears extjs" "turbogears repoze"
"turbogears openid". My point is that the 2.1 doc tends to become the
default doc for TG, even for newbies.
That's why IMHO this doc should be polished a bit further... And I
have meet some concrete issues.
- Big images are not displayed correctly: http://turbogears.org/2.1/docs/main/explorequickstart.html
- The main content area is not large enough:
http://turbogears.org/2.1/docs/main/Auth/Customization.html
the code samples are hardly readable
- It's hard to navigate within the doc, sometimes you can get lost.
For example, I've googled "turbogears chameleon", the first result is:
http://turbogears.org/2.1/docs/main/Templates/ChameleonGenshi.html
Well not too much info... That's why I want to find info regarding the
other templating engines. There should be a parent page or
something... I don't see anything the the TOC. So, I have to truncate
manually the URL to go to http://turbogears.org/2.1/docs/main/Templates...
Not very straightforward.
I know how hard, tedious, time consuming it can be to build a good
documentation, but I really think there should be more improvements.
Nice doc make the community happy :)
So, here is my 2C: The central zone width should be dynamic, adapted
to the screen resolution (perhaps with a max width).
Then, I don't know if this is easily possible, but images should be
shrunk and user could display them entirely with a click, in a modal
popup for instance.
Finally, the TOC sidebar should be out of the central area, to have
more space (the zone under the sidebar is always blank). Cherry on the
cake, it could be contracted/expanded with a mouse click.
Cheers.
timblack1
> Finally, the TOC sidebar should be out of the central area, to have
The Sphinx docs say that when you're using the default theme, the
sidebar can be made collapsible, but only when the sidebar is on the
left side of the page. Perhaps someone could figure out how to get it
working when the sidebar is on the right side of the page, then we'd
have a little more readable docs. It looks like a key part of the
collapsible sidebar code ends up in _build/html/_static/sidebar.js, so
that might be the place to start.
Tim
Christoph Zwerschke
> The Sphinx docs say that when you're using the default theme, the
> sidebar can be made collapsible, but only when the sidebar is on the
> left side of the page. Perhaps someone could figure out how to get it
> working when the sidebar is on the right side of the page, then we'd
> have a little more readable docs. It looks like a key part of the
> collapsible sidebar code ends up in _build/html/_static/sidebar.js, so
> that might be the place to start.
A collapsible sidebar is a good idea for people with limited screen
width. I'll try to implement it in the new layout. Maybe we can even
allow switching the sidebar from the left to the right side.
However, I don't like the idea of having the side bar on the right as
default. My reasons are, first, the left side is where you usually
expect the navigation and table of content in left-to-right writing
cultures. Second, I see the sidebar as extension of the bread crumbs
(expansion of the last bread crumb) which are (left-eligned) on the
*left* side of the top bar. Of course we could move the bread crumbs
(right-aligned) to the right side, but that would look even more
unusual. Plus, we already want the search field on the top right since
that's also a common place.
-- Christoph
Tim Black
Am 15.10.2010 09:02 schrieb timblack1:
The Sphinx docs say that when you're using the default theme, the
sidebar can be made collapsible, but only when the sidebar is on the
left side of the page. Perhaps someone could figure out how to get it
working when the sidebar is on the right side of the page, then we'd
have a little more readable docs. It looks like a key part of the
collapsible sidebar code ends up in _build/html/_static/sidebar.js, so
that might be the place to start.
A collapsible sidebar is a good idea for people with limited screen width.
I'll try to implement it in the new layout.
Maybe we can even allow switching the sidebar from the left to the right side. However, I don't like the idea of having the side bar on the right as default. My reasons are, first, the left side is where you usually expect the navigation and table of content in left-to-right writing cultures. Second, I see the sidebar as extension of the bread crumbs (expansion of the last bread crumb) which are (left-eligned) on the *left* side of the top bar. Of course we could move the bread crumbs (right-aligned) to the right side, but that would look even more unusual. Plus, we already want the search field on the top right since that's also a common place.
Tim
Christoph Zwerschke
> The problem isn't limited screen width, because the 2.1 docs
> have a fixed layout.
The current 2.1 docs have many layout and usability issues, this is only
one. I had already suggested a new layout with variable width body and
sidebar on the left, and was talking about that:
http://www.turbogears.org/docs/playground/docsprint201010draft1/main/movie_tutorial.html
Things that will be changed in the next revision of the new layout:
No fixed footer, search field in the top bar on the rigth side, sidebar
made collapsible and maybe movable.
Note that so far we are only discussing the coarse layout (placement of
blocks, whether they should be fixed, fluid etc.). The details of
borders, colors, fonts, gradients etc. can be improved later.
-- Christoph
Tim Black
Am 15.10.2010 17:41 schrieb Tim Black:
The problem isn't limited screen width, because the 2.1 docs
<http://www.turbogears.org/2.1/docs/> do not have a fluid layout; they
have a fixed layout.
The current 2.1 docs have many layout and usability issues, this is only one. I had already suggested a new layout with variable width body and sidebar on the left, and was talking about that: http://www.turbogears.org/docs/playground/docsprint201010draft1/main/movie_tutorial.html
Things that will be changed in the next revision of the new layout:
No fixed footer, search field in the top bar on the rigth side, sidebar made collapsible and maybe movable.
Tim
Tim Black
Pastor, Caney Orthodox Presbyterian Church, 206 N. Vine St, Caney, KS 67333
Web Developer & Owner, Always Reformed Web Development, 801 S State St, Caney, KS 67333
o (620) 879-2359 - h/o (620) 306-4624 - c (620) 306-1507
timblack1 on most chat networks - timblack11 on Skype
Christoph Zwerschke
> Things that will be changed in the next revision of the new layout:
> No fixed footer, search field in the top bar on the rigth side,
> sidebar made collapsible and maybe movable.
Ok, the next revision is online for review:
http://www.turbogears.org/docs/playground/docsprint201010draft2/tutorials.html
Let me know what you want to see improved.
The sidebar can be collapsed and dragged to the right side bar, but does
not yet store its position, only the collapsed state.
-- Christoph
Tim Black
Tim
Tim Black
<div class="related"> page header obscures the heading to which the link
points. But maybe this isn't a problem that needs to be corrected at
this stage.
Tim
Michael Semcheski
> Ok, the next revision is online for review:
> http://www.turbogears.org/docs/playground/docsprint201010draft2/tutorials.html
> Let me know what you want to see improved.
> The sidebar can be collapsed and dragged to the right side bar, but does not
> yet store its position, only the collapsed state.
I just wanted to say that I find the new version to be a big
improvement in terms of navigability.
The Gears in Detail page is very useful to me.
Well done!
Christoph Zwerschke
> Links to internal anchors don't scroll right in FireFox, because the
> <div class="related"> page header obscures the heading to which the link
> points. But maybe this isn't a problem that needs to be corrected at
> this stage.
I see what you mean. Not sure if there is a simple solution keeping the
page scrollbar instead of an auto overflow scrollbar inside the page.
Anyway thanks for the feedback. I'll create a tickets for these things.
-- Christoph
Fabrizio Mancini
> Ok, the next revision is online for review:
> http://www.turbogears.org/docs/playground/docsprint201010draft2/tutorials.html
> Let me know what you want to see improved.
> The sidebar can be collapsed and dragged to the right side bar, but does not
> yet store its position, only the collapsed state.
first of all a big thanks for the great work. The new documentations is great!!
I've noticed on the new docs that from the main page if you go to
Advanced Tutorials -> Using Toscawidget to Create Forms
[http://turbogears.org/docs/playground/docsprint201010draft2/main/ToscaWidgets/forms.html]
in nearly all the section the code snippets doesn't display.
HTH
Fabrizio
Christoph Zwerschke
> I've noticed on the new docs that from the main page if you go to
> the section the code snippets doesn't display.
Thanks for the feedback, Fabrizio. This was only intended as example for
the layout, I haven't cared much about the content. But in the third
draft I've fixed this now:
http://turbogears.org/docs/playground/docsprint201010draft3/main/ToscaWidgets/forms.html
-- Christoph
mr....@gmail.com
Inviato da iPhone
Il giorno 21/ott/2010, alle ore 00:23, Christoph Zwerschke <ci...@online.de> ha scritto:
>
> Thanks for the feedback, Fabrizio. This was only intended as example for the layout, I haven't cared much about the content. But in the third draft I've fixed this now:
>
> http://turbogears.org/docs/playground/docsprint201010draft3/main/ToscaWidgets/forms.html
>
> -- Christoph
>
Many thanks to you for the great work again!
Fabrizio
Michael Pedersen
week, and I'm really glad the sprint isn't until next weekend.
That said, the new layout looks amazing. Just amazing. My only
complaint at all is that I wish I could have made it. You've done an
awesome job.
--
Michael J. Pedersen
My IM IDs: Jabber/pede...@icelus.tzo.com, ICQ/103345809, AIM/pedermj022171
Yahoo/pedermj2002, MSN/pederm...@hotmail.com
Tim Black
http://www.turbogears.org/2.1/docs/gettingstarted.html#getting-started
better than on the "draft" docs:
http://turbogears.org/docs/playground/docsprint201010draft3/gettingstarted.html#getting-started
Also, I notice that in the latter, links are the same color as regular text, which is a usability problem. Other functionality in the "draft" docs looks very good, though.
Tim
Christoph Zwerschke
> I don't think it's time yet for comments on the colors and graphics,
> but I'm sure you're thinking about them, so will comment that I sure
> than on the "draft" docs.
Colors are certainly a matter of taste. In any case, I agree, everything
must be clearly readably, and links should be clearly distinguishable
from plain text even if you're color blind or have a badly calibrated
monitor.
For the draft, I've created a Sphinx theme where all the colors are
configurable, so we can easily change them back to the color scheme of
the current 2.1 docs, or experiment with other colors.
-- Christoph