Usability of Ice-Manual.pdf - or lack of

[grembo]

Hi,

The new Ice-Manual.pdf needs layout improvements, it looks like a printed wiki and is really hard to read (font size, borders etc.). The old manual had an almost perfect layout allowing to read it cover to cover - a few years ago when I looked first at Ice the well structured and beautiful manual - basically a real book - was what convinced me to give it a shot - because I made it to the point where you start understanding why to use Ice - wouldn't have happened reading this. Also the new Ice-Manual.pdf takes forever to load and crashes Safari reliably here (MBP 2.5GHZ dual core, 8GB RAM, SSD, not "underpowered") - which is kind of a turn off. To me it doesn't matter that much (and for the time being I will continue to use the 3.4.1 PDF), but I think to attract fresh blood you need to provide something more professional than that (giving the thing a cover page would be a start).

Just my 2 cents

[marc]

Our main documentation is now the online version: Home - ZeroC Documentation - ZeroC

In essence, we switched priorities: Instead of having a nice print version and generating a mediocre online version from it, we now have a great online version, with the unfortunate consequence that the PDF doesn't look as nice. How the PDF version looks is mostly out of our control now, since we use the features of our Wiki software (Confluence) to generate it.

That's the downside, but we believe that the online version is more important, with respect to structure, search, and most importantly, it is a lot more flexible in that it is much easier and faster to fix problems or to add to the documentation compared to FrameMaker.

[grembo]

I understand your need to have a good online reference manual and wiki (and you explained that in your release notes), but sacrificing a readable PDF seems ill-advised.

The main reason why I'm stressing this is because to get people into a new technology it really helps to have a book to start with. As far as I understand there is not a single third party publication on how to get started using Ice, so having a well designed book describing the technology and developing an example over time is just great (load the thing on your tablet and read and learn while flying).

On the other hand - Confluence is a commercial Wiki software (and not the best looking one IMHO but I'm certain you had a thorough decision process that resulting in choosing a slow, closed source and Java based Wiki solution which lacks proper export functionality) and I would just assume that you could do simple things like setting a front page, increasing the font size, set reasonable inner and outer borders that make it readable at all. Still not sure what they're doing in the export, but all I can say is, if I visited your web page for the first time and clicking the link to the printable manual crashed my browser (or to be more precise: send it into a runaway), which makes me lose all my open tabs (that's what just happened), and keeps doing that every time I open it, I'm not sure if I would continue to explore the technology created by those people.

Sorry for being negative, but I believe in giving feedback, even if it's not what people like to hear. On the positive side the new online documentation looks better than the old one - I just think it could look even better and could've been done without ruining the book.

[marc]

Thank you for your feedback. We indeed evaluated many different Wiki solutions and, without going into technical details, Confluence was our preferred choice. I guess we can't make everybody happy, as some Ice users didn't like our online version and told us the exact opposite of what you just said, namely that it wouldn't be good for Ice to not have a top-notch online manual :-)

While not exactly a manual, you should check out our training material if you are looking for printed Ice documentation: ZeroC - Training Courses

While this is not a full-featured manual, the Student Workbook is quite extensive as well.

[grembo]

Can't deny that having a good online documentation is crucial. Still would've liked to see both, but well... that's life I guess

[grembo]

Things like title page, fonts etc. seem customizable though:
Editing the PDF Stylesheet - Confluence 3.5 - Atlassian Documentation - Confluence