AAAAARRGGHHH!!! Nobody writes real documentation anymore... WHY?

Fri, 01/09/2009 - 17:22 — Anonymous

Just got the iPhone app. Running v1.7.

I hate to complain when getting something for free, but... aside from the fact that Stanza Desktop is going to be a pay-for app when it's out of beta, I really, really want a great reader for the iPhone, and being noisy and obnoxious tends to help.

So, my beef...

You've put so much effort into the product/site/etc. There's "documentation" on the phone and on the site. You have forums and FAQs. You have a ten-minute intro video on the iPhone version.

All this stuff takes time.

Why, then, when you've invested so much, do you skimp on explaining all but the less obvious features of the app? I'm not a font/text/reader expert. When modifying reader settings, I know a few things - fonts, for example, aren't a huge mystery.

But, for example, I don't really get the "Display Styles" option. It doesn't seem to do anything. All I know is that the PDF book I'm reading looks far, *far* better using the iPhone's built-in reader. I feel like "styles" might have something to do with it. Stanza doesn't seem to be displaying the book with all its formatting intact. In places, text runs together, headers don't appear as headers, there seem to be captions without images (even though I have images turn on), and changes in font aren't reproduced.

Some headers show up as "Untitled" even though they aren't (or perhaps weren't properly formatted to begin with when the publisher created the PDF - but, still, Apple's reader displays it all properly).

It brings me back again to that "Display Styles" option. I get the feeling that, when activated, and when working, everything would appear as it should. I've been focusing on it because, as far as I can tell, nothing else is going to fix it.

The bug aside (if it *is* a bug - hard to tell when docs are insufficient), so many questions could be answered if, rather than trying to have fifty different ways to get to the same information (eBook docs, site docs, forums, FAQs), you just wrote good docs. It can't be that hard (I know for a fact it isn't, actually - "it can't be that hard" is the tactful way of putting it, the tactful aspect of which I've wrecked with this parenthetical comment).

For serious. Some things are even a touch offensive. Why would you spend time creating a "Random FAQs" feature (if "feature" is the right word) when you haven't even covered the app in your docs?

I watched the ten-minute video intro. Looked like an older version of the app. Didn't have the "Display Styles" option, but it wouldn't have mattered anyway - when the presenter got to the reader config screen, he talked about the font options, but, when he moved on to the less self-explanatory bits, he referred to the options as "a bunch of others" and continued on his merry little way. As I said, "Display Styles" wasn't in that version, but it's still funny that, right where the video *would* have picked up where the documentation left off, it simply didn't.

I don't understand why so many companies have gone this route - creating skimpy docs, augmenting them with FAQs, and then relying on their confused users to do the rest in forums.

It's a waste. You must have people scanning the forums. That takes time. Time that could have been spent doing something else had the docs been complete. If you'd actually covered the app's options, I wouldn't be here wasting your time. At least not about this - I think the lack of formatting is probably a bug, so I'd have said something about that in its own post, but that's a different story (though related).

That's all.

To summarize the info without the ranting:

1. Incomplete documentation means your product is only partially documented. That's bad.

2. Of all the things to focus on, it would be nice to see docs for the less obvious options rather than the ones many of us use on a daily basis (setting fonts, colors, etc.).

3. It's totally possible to provide completed docs - just stop spending so much time working on site features intended to compensate for incomplete docs. Spend a few more minutes on the docs themselves. *I'll* write the section if you just tell me what "Display Styles" does.

Thanks for your time. I really do appreciate the app. It has great potential, and I look forward to future versions (but I won't pay for anything until it works right - proper formatting, displaying images, etc. - basically, until it renders PDFs as well as the native iPhone reader).

And apologies for any harshness. I've been in the software industry for years, and I know what it takes to write docs. I also know what it's like to be at an extremely small company where a few people do the work that a corporate giant would send fifty to conquer. Therefore, I know what's possible. That's why I'm uppity.

P.S.

The CAPTCHA thing is giving me trouble. I got it wrong the first time, so it tells me. I'm Ok with that. Me 'n CAPTCHA - we had an understanding.

But, when I scrolled down... no CAPTCHA.

Had to come back and reenter the title and tags (just pasted the post in - I'm used to web forms getting all wonky).

Thu, 02/19/2009 - 17:12 — Anonymous (not verified)

You misunderstand me, sir - or something like that.

magicjj -

"First of all, breathe. Get a chillaxative. They work faster than chill pills."

I'm not sure how that could be the case. Seems to me that a chillaxative would require special equipment, a (potentially (depending on what you're into)) uncomfortable process, and cleanup duties at the end.

A chill pill can just be swallowed. You can chew them to get a little head start. Some can be absorbed sublingually, which is a quick way of getting the chill chemicals into your system. If the pill in question is water-soluble, and if you're able to separate the chill from the filler, you might even be able to grind it into a fine powder and insufflate or inject.

But this is a discussion for another forum. One that most likely appears nowhere on this site.

"Second of all, the next time you write an excruciating rant post and then decide to summarize (minus the ranting) at the end, I would appreciate a note at the top of the page informing me of the summary. This way, I could choose to skip the rant."

Done.

I've made a note in my Preferences of Internet Users Who Isn't Me book to remember how to properly format posts when communicating with you, magicjj.

"Thirdly, this is NOT a bug. When you convert documents using Stanza Desktop it strips the styling (or at least the vast majority of it) from the book."

It would be better if it were a bug. Stripping the styling makes some books unreadable. I haven't been using Stanza because of this, and I don't see myself becoming a customer (whatever that means - I don't know what the plan is with this product) until it's fixed.

I also don't understand why it's done. I used Microsoft Reader for years, and the books, including ones I converted myself, displayed properly. I can't imagine that, for Stanza, it's a problem of resources, as the iPhone has much more to offer than the original Compaq iPaq 3630/35, which was the first device I used for ebooks.

One of the draws to Stanza was its flexibility with format. Seemed to be able to open just about anything (much of what I have, anyway). But if it can only open documents in this limited way, then, I'm sorry to say it, I don't see the value.

"All disabling styles does is strip the styling from any text that has styling, making it normal text (i.e. Styles are things like bold, underlined and italicized font.)."

Ok... it didn't seem to have an effect on what I was reading (PDF technical book). On or off, it didn't seem to make a difference. You mentioned that Stanza Desktop strips styles - maybe that's what happened. I don't know. It's not especially intuitive. Had I known it would do that, I wouldn't have started the process in the first place.

And that brings me back to my original complaint about manuals. You wouldn't see people posting here in a manner judged chillaxative-worthy by some if there were some central guide that contained all this information. Something like... a manual.

It's a feature that seems self-explanatory. When I saw it, I thought I knew what it meant. But it turns out that, although I *did* know, I didn't realize there were factors beyond that little switch that affected whether styles would appear. Obviously, if styles aren't present, they won't appear, nor will they appear to disappear. The switch just seems broken.

One entry on that "feature" in a manual would have saved time and effort for multiple people. Me, you, whoever else is reading this...

It's just wrong. Users are going to expect their documents to render properly on the phone. Different fonts, yeah, but otherwise with all the meaning imparted by styling intact. There's no reason to think the desktop component is going to strip styles out of the documents. There's no option to stop it from doing that. At the very least, if styles have been stripped, that switch should be grayed out (or not appear at all). But that's for people who are fine with having their books modified like that.

I'm repeating myself, I know, but I still can't believe styles are stripped. If it's only for books converted using the desktop tool, then what about other books? This implies that there are books, probably from the store (didn't use the store, so I don't know) that contain styling. Why can *those* books contain styling, but the ones I import can't?

Makes no sense.

Does it depend on what the original format is? That is, if I want to import a PDF, will it have its styles removed no matter what? And if I wanted to import something else (HTML, maybe - I dunno - just another format), then will the styles be retained? Or is it *everything*?

What I'm getting here is that, if I don't buy books through the store, then all I get to read are butchered versions of what I already have.

*This* is why I need to write my own reader.

"Like I said, Stanza Desktop strips these already. If you use a different converter (such as Calibre) on a document that has styling, you will only see that styling if "Disable Styles" is turned off in your settings."

That sounds great, but I don't know what Calibre is, nor do I want to. I just want Stanza to work correctly. I realize that "correctly" depends on who's defining its feature set - in my case, as a user, "correctly" means that my books appear more or less as I expect them to, which is more or less as they do in their original formats. Differences between desktop and device are unavoidable, so that's fine, but the iPhone is perfectly able to display italic, bold, and underlined text. Stanza also seems to have a problem with certain types of layout - block quotes (if I recall) and just about anything that positions text in any way other than simple paragraphs.

These may not be bugs, but they should be treated as such.

"As for the title being "Untitled," that's a different thing altogether. Stanza pulls the list view of titles from a the phone memory, so you can edit these. When you open a book and see the title, it's pulling this from the actual book file. Stanza Desktop does not give you the ability to change this information. Again, if you use a different convert (such as, guess what, Calibre), you can edit this information and it will show appropriately."

I accept this, but don't understand why it's this way. If my PDF on the desktop has a title, I don't see why that title isn't carried over when the book is imported.

I should be able to import a book. That's it. And that's all I should have to think about. I should be able to drag and drop something in a compatible format to Stanza's import tool, and then read that book, intact, on my phone. I should never have to think about styles being stripped (or not stripped - I don't know what the criteria are for stripping style information), shouldn't have to think about metadata that's already built into the original document, and I shouldn't have to consider using a third-party app to get the job done correctly.

I just don't see what the big deal is. Writing an app that acts as a repository and reader for your books can't be *that* hard on the iPhone. PDF support is built right in and is made available through the SDK. It's not hard to whip something up to transfer the books to your phone. It almost sounds like I *would* be better off going with something homebrew...

Fri, 02/20/2009 - 10:05 — withak

You should demand a refund.

Fri, 01/09/2009 - 18:37 — Anonymous (not verified)

Thanks, magicjj. Here are a

Thanks, magicjj. Here are a few clarifying remarks:

You can edit author/title information in Stanza Desktop (beta 15) by going to View->Book Info, entering the information. The information will be displayed if you share with Stanza iPhone, and it will display after doing a Save As or Export, closing, and reopening.

You can also edit author/title information directly in Stanza iPhone, by opening the book, tapping in the center, selecting the "i" icon in the upper right corner, and then tapping Edit in the upper right corner.

See this FAQ for more information:

http://www.lexcycle.com/faq/change_title_or_author

Also, Display Styles does not necessarily strip out italics and bold. I think that the "styles" referred to here are the styles in a cascading style sheet, which is sometimes included with some epub files to provide extra formatting information.

Fri, 01/09/2009 - 18:02 — magicjj

display styles

First of all, breathe. Get a chillaxative. They work faster than chill pills.

Second of all, the next time you write an excruciating rant post and then decide to summarize (minus the ranting) at the end, I would appreciate a note at the top of the page informing me of the summary. This way, I could choose to skip the rant.

Thirdly, this is NOT a bug. When you convert documents using Stanza Desktop it strips the styling (or at least the vast majority of it) from the book. As a result, disabling styles will not change the way your document appears in Stanza. Styles are things like bold,

underlined

and italicized font. All disabling styles does is strip the styling from any text that has styling, making it normal text (i.e. Styles are things like bold, underlined and italicized font.).

Like I said, Stanza Desktop strips these already. If you use a different converter (such as Calibre) on a document that has styling, you will only see that styling if "Disable Styles" is turned off in your settings.

As for the title being "Untitled," that's a different thing altogether. Stanza pulls the list view of titles from a the phone memory, so you can edit these. When you open a book and see the title, it's pulling this from the actual book file. Stanza Desktop does not give you the ability to change this information. Again, if you use a different convert (such as, guess what, Calibre), you can edit this information and it will show appropriately.

Hope this helps,
Jake

Thu, 02/19/2009 - 20:42 — bubblybabs1 (not verified)

doc files and the unknown problem

Quote:
"As for the title being "Untitled," that's a different thing altogether. Stanza pulls the list view of titles from a the phone memory, so you can edit these. When you open a book and see the title, it's pulling this from the actual book file. Stanza Desktop does not give you the ability to change this information"

For Doc files:
Right click on the file in question
Click on properties
Click on details

Type in the name of the file and the author and any other info you wish to add...

Now, when you open the file in Stanza desktop, the information will show up correctly and will be correct in the stanza app on your iphone... This does not seem to work for pdf's or text files...

Babs