On 6/21/07, Rene Rivera <[EMAIL PROTECTED]> wrote: > OK, managed to find time, while waiting for some long compiles...
Great! Thank you very much for taking the time to analyze every bit of the design. A few words of warning. I am not a web designer :P In the past two weeks I have learn from scratch: * xslt * xhtml * javascript * boostbook internals * quicbook internals I have never touch this things before. I had some basic knowledge of css, and I have learned a lot in the past few weeks. So... do not expect to be talking with an expert on the field ;) I am eager to learn and I have liked all this web stuff a lot more than I expected. A lot of people have been helping me with the details that you will only learned with years of experienced (like Daniel James with ie6 support, that I have not yet included). I think that is the magic of a project like boost. That is the reason I really appreciate your comments. I think that I have made a good job til now, but it is obvious that all this stuff will be not perfectly cross-browser at this stage (The syntax selectors has been hacked 30 hours ago!). I really care about cross-browser stuff (if we are talking about a decent browser like ie7, firefox or opera). I do things for firefox and test them on ie6 (in windows and linux) and then put them here so others can help me porting them to others browsers. I believe in collaborative work, and in this case it is the only way to go since I lack (for the moment... I will try to read the stuff you recommend me) some knowledge (like ie6 or opera quirks). I have been doing with six thing in minds: * Aim at standards, Only use stuff if I found it in the W3C page. * Construct flexible stuff (i.e. The important thing about box-wrappers is that we now can do whatever we want with our blocks, have they look now, the size of the shadow, etc, can be easily changed later... for example as the result of a discussion with someone that really knows about web usability like you) * Aim at simplicity * Do not clutter the screen * Hack where you have to (if necessary change boostbook, quickbook, the css or even sending emails to docbook folks, always with backward compatibility in mind) * Document a lot! Ok, sorry the long introduction but I really think you must give all this work some time to stabilize. I can work on my own and show you perfectly tested result in two months but I really prefer the continuous feedback of the last two weeks. To the business... > 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>. It validates XHTML 1.1, The document type is wrong because I have not attempt to change it yet. I have used "Total Validator", a firefox extension that let me choose what doctype I want to use. I have not yet try to validate the css. The only errors I see seems to be with some fonts style. It will be very easy to fix when I get some time. Thanks for spotting it. > > * 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. Ok, I see what you mean. In the Yale U. Press web site you acknowledge as good design they are using select boxes in the header banner too. I really think they are very useful, maybe we can came up with a different layout in the banner. > The search box doesn't land at the same Boost custom Google search page. ja! that is what I mean when I talked about this two weeks old project. The google search use a new technique called linked cse. You send google an xml definition witch let us do some pretty neat stuff like customize the google page for each library, so it serves as an index too. I played with this stuff for a day, put the machinery to work and the ask for help here to complete the details while I was working on other stuff. My help request still stand and I hope someone will jump in. If not I will revert it to the beta google search style for the moment. > 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. Oh, thanks for pointing this out. I do not think it will load up the header if we use the watermark trick they propose. > 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. Sidebars has to be optional in the docs. 100% agree. I really think we can came up with a layout of the header banner that is well proportionate and include this useful navigation aids. > > * 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. Ok, I will look into it. > 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. Ok, the current box-wrapper style is a 20 minute first try. Having read all your comments, specially the one about the shadow being an undesired division bar, I think the shadows are too heavy now. Lets try some other styles and then we choose. I will try to start a boostbook style repository. Now that all the css is modular, we can have different version of the pieces and assemble a final version later. > 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. I like it, I will make a proof of concept with a similar scheme. > _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. You have lost me here. When you select Visual Studio syntax, all code, including inline code are coloured like VS does. The menu being in the corner of code boxes is just a goody. If you have a decent browser, you go to "View" --> "Page Style" and choose there the style you want. > 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. Oh, you are right. I will add code links in the test doc. > 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. Ok, I see your point. The hover effect can be removed. > 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. I think that code must be limited to 80 characters. And with this rule you do not need the scroll bars except you are reading the docs from a cell phone ;) Anyway it will be nice to prevent the overflow. Can we hack the css to do word wrapping? > 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. Yep, lets try to reduce it. > _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. I done exactly this in one of the early iterations! You may have missed it, we can give it a try. > The hover highlight is misleading in the admonishment context. There > just isn't anything interactive about the box. I like it here, because it calls my attention when I want to skip it :) But again, if usability gurus tell us to remove the effect, we can remove it. > _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. Great! ( And I have been making logos for a lot of libraries :D, so they have already something to insert there ) > > * 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. I like the idea. I will try to implement it. > > * 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. mmm... I do not mean, perfectly matched but the general look & feel of both things must be close enough to make you realize they belong to the same project. > > * Simplify and document boostbook params > > Yea, documentation is always good :-) I love docs :D > > * Start a collaborative effort to translate html to qbk > > Much appreciated. Thanks again to the ones that volunteer. > > * 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. I do not know if you have seen the thread about this, but Joel is working on a new template for an image in quickbook that will let us perform scaling and other useful things. > > If I recall what you have said before your woes where: > > --> 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. Ok. > > --> 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. I will try to read it. > > --> 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. I will look at your work in the beta pages to see how fonts must be treated. > > --> 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. Ok. > = 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. I really like it. But again... I do not care about removing it. > 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. Good. > _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. Yep, you are right. I will correct it. > 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/>. Thanks for all the pointers! And thanks again for this review. Lets work together to make the best docs ever ;) King regards Matias ------------------------------------------------------------------------- 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
