Rene Rivera wrote:
The big warning about the docs, as they are presented on the beta web site: They override, disregard, and literally throw away the style information in the source docs. How that happens is that the ZIP archives for all the release are put on the web server. The doc section pages, when requested to open one of the version specific doc files, opens a specific archive and expands+reads the file into memory. It then post processes that file, on the fly, stripping out all of the header and footer content. It also does some number of cleanups and fixing in the content itself. Currently that is done via structured regex search+replace manipulation, but I'll be changing that at some point to do DOM manipulations now that the server has PHP5. The doc is then incorporated back into the web page one sees with the standard header and footer for the web site. The CSS used is entirely different than the one in the document at this point, since it comes from the standard web site style!
I thought that one of Matias's aims was to develop "one true style" suitable for the web, Boostbook .css and pdf formats. Especially now that more and more of Boost is getting "quickbooked".
The style used for the docs is designed, and inherited, from the style for the rest of the site (exemplar page <http://beta.boost.org/development/exemplar.html>). There are additional styles to handle the variety of elements and changes over time that the Boost docs have had, and are still having ;-) The presentation architecture has some consequences for Matias styles, and other author's styles... They will *only* be visible in the downloaded release, iff they are generated by the authors themselves. The content of the header, i.e. the search box, will not be available on the web site. And hence will *only* be available in the downloaded release. This also happens to be the one context under which it's likely not usable as the person might not have network access.
IMO that would be a huge shame: have you seen the navigation lists Matias has added : http://www.drivehq.com/web/matias.capeletto/bimap/doc/html/index.html these are just so cool and *useful* that propagation of these to the web site is surely a must have feature, once Matias has the details worked out.
Changes to the style of the docs are less likely to make it to the web site than changes to the release style. This is intentional, as it's important to keep a consistent look & feel on the web site. Both for usability and presentation quality of the web site. It means that changes to the web site style have to arbitrated even more than changes to the release doc styles. Now, commenting on Matias doc style <http://tinyurl.com/2hxdsm>... I like the navigation icons. The one change I would make would be to the home icon. It's outline is not as clearly a house as the black&white one. Which takes a bit more visual effort in noticing what it is. It also looks like if the house icon is simplified a bit it would be just as easy to create a vector version of it as it looks like it would be of the others. I'm guessing, but it looks like the software Matias uses is already operating with vector sources.
I agree that's probably the weekest of them: but still better than the Docbook default IMO.
Not specific to Matias doc style, but the BoostBook style. The headings are too big. This is likely because of the usual style escalation present in so many documents.
I disagree, and find the heading in the website syle too small. Sorry.
Irrespective of the code colorings, I don't like the code background color, nor the heavy border around it. The use of such heavy style elements should be reserved for attracting attention only. For example in sidebar notes, warning texts, etc. And I've mentioned this before; Having it in the regular flow of text interrupts reading and comprehension. In that it obscures the over all structure of the document.
Difficult one this, I'm very much in the "less is more" camp here, but I do find that a slight tint to code blocks helps out. I'm neutral on the border issue.
The size of the code text is too large. This again elevates the code in importance above the regular text. IMO the code text size should always be either the same, or preferably smaller than the regular text. The reason I say preferably is because it's very hard to tell size equality between two different font families. In particular, even though the two sizes Matias is using might be the same, the Courier font looks bigger because it has wider characters. I.e. it looks like it occupies more space. (Contrasting example from the web site style http://tinyurl.com/35lg32.)
I agree the code should be smaller than the body text, and I believe it is: 9pt rather than 10pt, and IMO about right. Maybe I'm just getting old, but I find the web page you reference really rather hard to read: in the code blocks especially the font is too small, and full of some strange symbols? See screenshot attached (Firefox on Windows).
I also find your titles rather hard to spot next to the body source.
This one is just an overall warning... For the code coloring, and with much everything else in text, one has to avoid to an extreme overusing style elements. For code this means that we should prefer using a style that *doesn't* bold, italicize, underline, and colors the majority of the text. Color and style should only be used for elucidating structure and meaning.
I think we all agree on that.
And another general issue... We have to keep in mind the less fortunate people who don't have the full capacity of their eyes. So avoid using light text on a light background, and of course the inverse. I.e. avoid low contrast arrangements. I see that Matias needs to make some of the elements of the images a bit darker in this respect.
Also agree, the code comments being the main culprit.
This also applies to the code block background color. Having a colored background decreases the dynamic range one has to play with, as it reduces the difference in luminance between the background and foreground.
Nod.Regards, John.
<<attachment: web-shot.png>>
------------------------------------------------------------------------- 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
