Rene Rivera <[EMAIL PROTECTED]> writes: > Obviously some authors are more capable > in this respect than others, i.e. Joel. But others are either not > capable, or don't care enough to put the effort into the presentation of > their docs.
And a few have an idea of what's superior that's at odds with what most other people can agree on. I think we just have to let them have their way, unfortunately, all other alternatives being more evil :( > So we are down to either totally imposing a design on authors, or > someplace part way there. Psychologically speaking I would think > authors would be happy to not have to think about visual design and > instead have their libraries stand out in the libraries code merits. As much as I enjoy visual design, I'm one of those. I just don't have the time to worry about it. If somebody could do a nice design job for me, I would love it. >> I am/was >>> questioning 1) the very rationale for creating a new design >>> *for the docs* (not the site in whole) in the first place > > Well there are really more questions, or parts to it. Whether to create > a new design for the BoostBook generated docs? [1] Whether to make all > documentation follow the BoostBook design? [2] Whether to have the docs > presented in a different style on the website? [3] > > My feelings on those, note: not really answers... > > [1] I have some objections to the BoostBook design just about all > stemming from my perception that the current design impairs structural > understanding of the docs. Basically because it violates a number of > understood design principles. One of those is the use of multiple visual > style vectors What's a "visual style vector?" > to indicate heading levels. Others are perhaps personal > readability concerns. For example the overuse of background "color" > (meaning non-background color) in text elements which break up the > structural flow of the text. In particular "pre" and "quote" boxes with > the gray background. Such design elements are causing the escalation What is "escalation?" > of other design elements (this is another design anti-pattern). For > example the large headers. And other minor items, like the > definition lists, etc. _So yes I think we need a "new" BoostBook > design._ One big caveat I should mention is that there are other > less functional issues, I also have. Like Joel I think the design is > somewhat drab and could use more visually interesting design > elements. I just didn't go that route because of my desire to > respect the previous "consensus". But the feedback I got from doing > the website design last year when I wanted to use different colors, > and interesting icons, etc. was one of "I just want the text" or > "don't put anything between me and the text". So it's hard to do > visually interesting designs with that kind of audience. Ouch :) > [2] _I do think we need to make all the documentation follow the > BoostBook design._ It's the least we can do for users to improve > their "Boost Experience". I also think authors would benefit from > not having to worry about this aspect of their library > documentation. After all it's hard enough for many to do good > documentation in the first place if they also have to worry about > making it look presentable, and not just making it readable. Yep. > [3] This is probably for me, personally, the most contentious > question because of the effort as the author of the web site > design. Just like Joel feels alienated for having to hand over > design control, I would feel betrayed if parts of the web site > content, the docs, do not coexist with the overall design. I think > we either use two (or more) different documentation presentations > for online and offline, or we agree on one design that can live on > both contexts. I don't see a contextual difference. It all ends up in a browser window, doesn't it? > Having said; _I believe we should have different design for online > vs. offline reading._ Because otherwise we would tie the web site > design down for longer than we might want. It would be considerable > harder to change our minds, and make improvements, to the web design > if each time we had to go back and redesign the offline BoostBook > design. This is a major goal of the new we structure, to separate it > from the Boost structure so that we are then free to tailor each to > the pertinent audience. I'm rather confused about what you mean by online and offline. >> Good questions. > > Yep they are. Hopefully my answers are constructive. And drive others to > comment. I'll probably be happy with anything you and Joel can agree on. -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------- This SF.net email is sponsored by: Splunk Inc. Do you grep through log files for problems? Stop! Download the new AJAX search engine that makes searching your log files as easy as surfing the web. DOWNLOAD SPLUNK! http://sel.as-us.falkag.net/sel?cmd=lnk&kid=103432&bid=230486&dat=121642 _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
