incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Sebor <se...@roguewave.com>
Subject Re: [RFC] Apache "look and feel" for stdcxx docs
Date Wed, 15 Aug 2007 18:20:41 GMT
Liviu Nicoara wrote:
> Martin Sebor wrote:
>> Hey everyone,
>>
>> Marc Betz has been working on the improvements to the stdcxx
>> documentation outlined in STDCXX-391. Most of them are pretty
>> straightforward and can, IMO, be implemented without much
>> debate (although feedback is always appreciated :) but there
>> is one that I think we need input on from a wider audience:
>>
>> https://issues.apache.org/jira/browse/STDCXX-506
>>
>> I expanded the .zip file containing a mock-up of Marc's proposed
>> changes and put it up on my home page:
>>
>> http://people.apache.org/~sebor/stdcxx-506/
>>
>> We're looking for feedback on the changes, positive or negative,
>> as well as suggestions for additional improvements.
> 
> I hope this is the kind of feed-back you are looking for.

All constructive feedback is welcome. If you have anything to say
on the subject the stdcxx documentation we want to hear it :)

> 
>  From a functional, informative point of view, both the banner and the 
> docs themselves are ok.
> 
> But from an artistic, look-and-feel, etc., pov they look... well, not so 
> good. The banner may be expressing the Apache membership alright but the 
> artistic impression is poor. The docs themselves, with the old-fashioned 
> three frames view and the ugly little blue buttons give me a strong 
> sense of deja-vu, ca. 1996.

I agree that it could use a face lift -- hence STDCXX-506:
improving the look and feel is the goal of the issue. I don't
have a huge problem with the buttons, although I don't think
they are very useful. I wouldn't be too bothered if we lost
them. What I find lacking in terms of functionality is the
navigation bar on the left.

> 
> I don't have any suggestions for improvement, but all the other pages in 
> the list I have looked at looked _much_ better, banners included.

Which list? Is there any project that you liked in particular?

FWIW, I like the Web interface to the Standard C++ Library
documentation for IBM XLC/C++ 9.0, especially the expandable
navigation frame on the left. I also like the shading around
code samples on the right. It makes the code stand out much
more than the red text color in our docs. I also like how
they enhance the function or class that's being documented
in bold in the code. Again, it makes it stand out against
the rest of the code. There are other nice things there,
like little colored icons (e.g., a green ones for AIX or
red ones for z/OS) indicating platform-specific features
or differences. Something like that would be really useful
in our docs because of the large number of platforms we
support.

http://publib.boulder.ibm.com/infocenter/comphelp/v9v111/index.jsp

Martin

PS Incidentally, have you noticed they already document TR1?
I guess that means XLC/C++ 9.0 comes with it.

Mime
View raw message