OK, managed to find time, while waiting for some long compiles... Matias Capeletto wrote: > Here is the last iteration: > http://tinyurl.com/3yukos > > Here is a list of the work we have done so far. It will be great if > you can comment on each item. > > * Validated XHTML 1.1 output (better than strict XHTML)
It doesn't validate as XHTML Transitional, which is what the document claims to be <http://tinyurl.com/ywrthx>. The CSS doesn't validate either <http://tinyurl.com/2y7xwx>. It doesn't pass the minimal Section 508 tests <http://tinyurl.com/27rszo>. It doesn't pass the minimal WAI tests <http://tinyurl.com/2emwt7>. > * New header and footer based on beta.boost.org. > * GroupedLinks select boxes for Boost Libraries and Section quick jumping. > * Google Search box over our docs. Retelling this one... But now with more detail: The header no longer looks balanced as it does on the web site. The various controls just don't fit in the header as far as I'm concerned. The controls outweigh the Boost logo, in various respects. They are collectively more massive than the logo. They are user active controls which users are trained to pay more attention to and hence distract from the logo. The search box doesn't land at the same Boost custom Google search page. AFAIK Google hasn't removed the requirement that one credit them when using their search engine. So you would need to add the Google logo, which would load up the header even more. It used to be that on the web site docs I would put the standard sidebar in the docs pages also. But that presented problems as it would squeeze the doc content for people with narrow screens. If I had to put search or other non-doc navigation content it would go at the bottom of the page, and I don't mean the footer either. > * Box-wrapper based blurbs that allow us to include rounded > corners, drop shadows, etc. Having the option, in the form of the extra divs is fine. The current box style is not. I need to comment on each of the contexts under which the boxes are used, but first some overall observations. Whatever styles you use it is important that they be available in at minimum IE7, preferably IE6. In particular you use the hover style which will not work in IE without some patching of the IE behavior. Search the web for this problem, and solutions. There's a css hover script I use in the web site you should use. Generally I don't like the shadow. I'll be repeating this same aspect many times; It escalates the importance of the boxed elements disturbing the perceived structure of the document. This causes one to overcompensate by making other aspects more strident, like the headers. For a detailed examination of this particular subject see "Web style guide: basic design principles for creating web sites" by Patric J. Lynch and Sarah Horton <http://tinyurl.com/yqhpfm>. And for that matter look at the Yale U. Press web site for an example of very good web site style. I'll be comparing to one of the pages from the current web site <http://beta.boost.org/users/license.html> for the rest just for reference. And I will point out why the web site style is the way it is along the way. Starting at the front... _Table of Contents_ Looking at <http://tinyurl.com/284z9y> it looks OK. But this is one where it's hard to tell how much impact it would have if you reduced the weight of the headers around it. I suspect it would look way more imposing than it needs to be. Even though I can see that the hover highlight is useful in this context as it's an interactive element. It doesn't really add to the usability of the TOC. Compare that with what the web site does of highlighting the entire row, and making the row click-able, for each TOC item. Which increases the hit aspect of the choices making them easier to use. It also removes any need to highlight the box itself as you get a much better direct response from the UI. _Code and Preformatted_ > * Alternatives syntax highlighting that simulates your own IDE > (move the mouse to the upper-right corner of a code block) It's a nice effect. But it has the effect of putting the control of how readable the docs are at the users hands which are the least likely to know what is most readable. It won't help in the code style for inlined code. IMO it would be better to have a single consistent code syntax coloring through all code contexts. I don't see an example of how links in the code blocks look. But I suspect the look of the links will impact the feasibility of using the differing syntax colors. Assuming one removes the syntax highlight choice... Having the hover highlight is misleading in this context. It leads to the belief that there is something interactive about the box contents, or the box itself. The code boxes suffer from overflowing code text when the box gets smaller than the content (the original boostbook also suffers from this). The web site style places an on-demand horizontal scroll on the block to prevent the overflow and still allow access to the content. Assuming you add a scroll to the blocks... It would make the rounded boxes look incongruous. Not only would it look strange to have a square scroll float in a rounded box, it would be unfitting with the rest of the users UI. Even though the border is sufficiently subtle to not interrupt the flow of the doc text, the shadow isn't. The shadow places the equivalent of a horizontal rule in the middle of what should be regular text flow. _Admonishements_ This is the one place where the shadow look very good. It has the desired effect of raising the importance of the block which is desired for admonishments as they should attract more attention. I might change the shadow to be a bit less prominent as I think you can get the desired effect with a smaller club ;-) The style for admonishments I've wanted to get working, and it may be possible now, is to put the admon icon on the outside of the box, to the left. If you then match the shadow of the box to a shadow on the icon it would make for an attractive layout. The hover highlight is misleading in the admonishment context. There just isn't anything interactive about the box. _Blurbs_ Same comments as the admonishments, since it seems blurbs are also meant to stand out. > * Chapter logo support Those are certainly good, as it's a good place for library authors to express some uniqueness to their docs. > * Modular css design OK. > * css based admonitions and navigation graphics OK, but you have to provide some alternate navigation for when people do not have images, in particular for vision impaired readers. You want to represent the nav as a structural element like: <ul class="spirit-nav"> <li class="prev"><a ...>Previous</a></li> <li class="up"><a ...>Up</a></li> <li class="home"><a ...>Home</a></li> <li class="next"><a ...>Next</a></li> </ul> If you want to see why this is important look at the license page on the web site, in Firefox, and select the "View/Page Style/No Style" menu. The page is still readable and correctly structured. When you do the same in the boostbook docs the navigation disappears. FYI, it took a *lot* of effort to get this right on the web site. > * PDF stylesheet matches the HTML style. Not sure what kind of matching this is but usually you don't want them to match. The design choices should match the rendering device. The choices I would make in making it look good in PDF (i.e. paper) are significantly different than those I would make for a web browser. > * Simplify and document boostbook params Yea, documentation is always good :-) > * Start a collaborative effort to translate html to qbk Much appreciated. > * Initial support for svg in html Again much appreciated... I talked with Joel some time ago about rendering graphics on web browsers. I suggested to use Flash as that has a good vector renderer and very wide browser support (it's even available in small embedded devices). Doing a translation from SVG to Flash is problematic though. I used to have a commercial tool that did this, but it seems to have been discontinued. Although there are some ongoing open source efforts. > If I recall what you have said before your woes where: > > --> The syntax colours (IMO this problem is solved) Not IMO, see above for reasons. > --> The green tint in the blurbs (I have removed it, and only appears in > hover) Which presents other problems as mentioned above. > --> The home icon (we are working to find new icons, the tango project > is the best we have for now) I wouldn't worry too much about it for now. > --> Headings too big (I do not agree here but lets see what others think) This is likely going to be my most contentious objection. But I suspect that after reading some of the Web Style Guide book you will better understand the rationale for smaller headings. > --> Size of code text too large (I have not played with this yet) Not terribly important, as long as it's not larger than the rest of the text. This one is actually very hard to get working correctly as font sizes across browsers and OSes is extremely difficult to make work. and speaking of text size, the way you've set up the overall font size prevents IE users from changing the size. This aspect of the web browser is very important as some users need set larger fonts to be able to read text. > --> Avoid using light text on a light background (We may have still > some places where this rule is not being respected) The more these can be improved the better. = Other Aspects = _Tables_ Hover highlight on tables is another instance of making something look interactive when it's not. Generally it's best not do deceive users this way. The border color for table cells, and the header color, looks OK. Not sure if I like the darker one I use or the lighter one you have. The padding is a bit more than I prefer, but not strong feelings here. _Lists_ Not sure if you are using the default indentation, but IMO it's too much. It's easier to see the structure of indented items when they follow directly below the item they indent. That's it for styles ;-) About the only other comment I have is that you really should test, and learn about cross-browser compatibility. There are numerous bugs when I view the pages in either IE or Opera. And I haven't even tried Safari, as my Mac is powerless at the moment. Suggestions on learning: * Web Style Guide (the one I mentioned above) * The W3 of course. * CSS reference with very important browser compatibility notes <http://www.blooberry.com/indexdot/css/index.html>. * Looking at other peoples work is always useful. I tend to visit CSSmania about every other day <http://cssmania.com/>. * The css-discuss wiki has some useful info also <http://css-discuss.incutio.com/>. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
