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.
