New book: Creating user-friendly Online Help

This forum is for all Flare issues not related to any of the other categories.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

New book: Creating user-friendly Online Help

Post by RamonS »

A new book about MadCap Flare was just released:

Creating user-friendly Online Help - Basics and Implementation with MadCap Flare
by Petra Thiemann and David Krings

This book is an introduction to creating user-friendly online help using MadCap Flare. The book provides in-depth background information that is applicable to other help authoring tools as well. The book does not only contain in-depth information about the research done about user-friendly online help, but also provides step-by-step instructions on how to implement the most important parts of online help using Flare. Tasks such as importing from Word and FrameMaker and working with DITA document sets are covered.
This book is ideal for technical writers that are new to the field of creating online help, but even experienced technical writers will find some interesting information about how to create user-friendly online help.

This book is a translation of the well-received book "Benutzerfreundliche Online-Hilfen: Grundlagen und Umsetzung mit MadCap Flare" from Petra Thiemann. Petra is a technical writer from Germany and has worked in the field for almost 20 years. The past ten years she specialized in online-media and is an active member of tekom, the German professional association for technical communication and Information-Development.
David Krings translated the book and added several sections to accommodate for the changes in MadCap Flare V5 and to provide relevant information about the legal framework as it applies to the US. David is a MadCap Flare MVP and worked for several years as a technical writer for software companies.

The book has 250 pages and colored pictures. The book can be obtained from the CreateSpace eStore:
https://www.createspace.com/3416509

The book is also available through Amazon:
http://www.amazon.com/Creating-user-fri ... 856&sr=8-1

A preview copy is attached. It includes the cover, the forewords, the table of contents, and the first chapter as a preview. After downloading you need to unzip the file to get to the PDF.
You do not have the required permissions to view the files attached to this post.
Last edited by RamonS on Sat Dec 19, 2009 7:54 am, edited 2 times in total.
Reason: Adding Amazon link
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: New book: Creating user-friendly Online Help

Post by NorthEast »

No freebies then? :o)
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

No freebies of the book (yet), but I can offer a free Office Suite. SoftMaker offers its Office 2008 as a free download and donates 10 Euro Cent per download to charity. See here: http://www.softmaker.com/english/
ksoltys
Propeller Head
Posts: 73
Joined: Mon Oct 20, 2008 5:38 pm

Re: New book: Creating user-friendly Online Help

Post by ksoltys »

Is this available in a download edition? Shipping to Canada, along with possible customs/brokerage charges could easily double the cost of the book.

Regards
Keith
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

Keith, let me look into that and see if I can find a better solution. In a few days the book will also be available through Amazon, but I do not know if that solves the issue.
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: New book: Creating user-friendly Online Help

Post by doc_guy »

Congratulations, David!!
Paul Pehrson
My Blog

Image
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: New book: Creating user-friendly Online Help

Post by SteveS »

Well done!

Anything about using Flare with Vista? :wink:
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
forfear
Propellus Maximus
Posts: 766
Joined: Sat Feb 16, 2008 3:37 am
Location: Jungle Jingles

Re: New book: Creating user-friendly Online Help

Post by forfear »

Great stuff!
If you submit your bug feedback request here, the more likely it'll get fixed or included in a future release
Open Utilities PageLayout Resizer for Flare/Blaze | Batch builder
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: New book: Creating user-friendly Online Help

Post by NorthEast »

Looks interesting.

This book was created with OpenOffice.org 3.1 and MadCap Capture.
But minus 10 points for not using Flare!
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

Dave Lee wrote:Looks interesting.
This book was created with OpenOffice.org 3.1 and MadCap Capture.
But minus 10 points for not using Flare!
There is a plausible reason for that. Flare was an obvious choice and I started briefly with Flare, but then when the import section was in the works it just got too confusing for me. At times I had projects for the book, the imports, testing, and the embedded help open. I tried different instances and working across two PCs, but none of that really made it easier. Having two different tools that look entirely different in every aspect made it easier for me to quickly switch thoughts. It may sound funny, but it worked for me.
Also, OpenOffice is an excellent tool that I know well and know exactly which output I can expect. Later on it also made more sense when I passed the document on for editing. My wife knows OpenOffice better than Flare. My decision was to pick what I consider the best tools for the task and I don't regret that decision at all. But thanks for dissing the book on a technicality. :lol:
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

SteveS wrote:Well done!

Anything about using Flare with Vista? :wink:
I mention Vista and Windows 7. Does that count?
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: New book: Creating user-friendly Online Help

Post by SteveS »

RamonS wrote:
SteveS wrote:Well done!

Anything about using Flare with Vista? :wink:
I mention Vista and Windows 7. Does that count?
LOL
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
helen
Sr. Propeller Head
Posts: 276
Joined: Thu Oct 25, 2007 5:57 am
Location: Manchester, UK

Re: New book: Creating user-friendly Online Help

Post by helen »

ksoltys wrote:Is this available in a download edition? Shipping to Canada, along with possible customs/brokerage charges could easily double the cost of the book.

Regards
Keith
Has there been any more ideas on this front? I'd like to purchase the book, but shipping to the UK and customs is too expensive on top of the cost of the book.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

No, there hasn't been any development into that direction. I will see what options are available.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

Hi!
I tossed the idea of a download around and hit some obstacles:
a) my current publisher (Amazon CreateSpace) does not offer this option for books.
b) a download as a PDF basically makes this a free for all, once one PDF is downloaded there is no control over how many copies of that download float around and what happens with the copies (OK, you can make a copy of a print as well, but it is not as easy). I am more concerned with where parts of the content would end up than people getting a freebie.
c) one option would be to publish in one of the DRM laden eBook formats that require the reader to buy a very specific and overpriced gadget that typically doesn't do anything more than show eBooks. Unless you have such a device the price savings are more than negated.
d) I could turn this book over to public domain, which will serve the community, but given the insane effort that went into this I am not quite that selfless. :lol: It would also not be fair to the original author.

To put this in perspective, the money I make with the sales is a few bucks per copy (so guess who gets the rest, but they do have a nice service - although it depends on from where you buy it). I share that with the original author. The goal is to offer this translation and have it more or less be financially neutral to me.
I can think of another option that may work out, but this is a case by case issue and if anyone is interested from outside the US please contact me through the private message function of the forum. I do want you to get a copy, but it has to be manageable for both sides and no, I do not get free copies *boooo*!
Eric Lachance
Sr. Propeller Head
Posts: 127
Joined: Thu May 13, 2010 11:51 am
Location: Montreal, Quebec, Canada
Contact:

Re: New book: Creating user-friendly Online Help

Post by Eric Lachance »

If I may offer a small comment on the book... I have a softcover version (if there are multiple, I don't know, it's orange/red/green) and I have to say the quality of this book seems a bit sub-par, in terms of presentation.

First, the cover of the book looks like a 72dpi JPG, there's compression artifacts everywhere around the words and the design. I would hesitate to buy any book with that sort of obviously cheaply thrown-together look.

Second, I started to read the first chapter and it's almost unreadable. Not that the text is not good, but the presentation, frankly, makes me want to puke. Double-interline paragraphs with large fonts, almost no spacing between the paragraphs, it's a big wall of text on each page that makes it hard to read, and even harder to get back to if you pause for a second to look somewhere else.

It almost seems like this was a PDF that was printed, and was originally meant to be as much information you could possibly cram in a small space, but then decided that the larger the book, the better - so you made the text and spacing larger.

Frankly, however decided on the style of this book would have a big advantage on reading something like "Creating reader-friendly books", or the Chicago Manual of Style or something.

Oh... and when you open the cover it says this was created with OpenOffice 3.1... isn't Flare good enough or user-friendly enough to actually write a book on using it to create documentation? That's the laugh of the day! Really now! Edit: just re-read previous comments. I understand why OpenOffice was used... but I don't think it's a valid argument. If Flare isn't good enough to write documentation on itself, then maybe it shouldn't be sold at all?
Eric Lachance
Technical Trainer
Objectif Lune Inc.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

The comments are welcome and for each point of criticism there is an explanation. Believe me, if I have had the time and especially the money to make a better looking book I would have done it.
Eric Lachance wrote:If I may offer a small comment on the book... I have a softcover version (if there are multiple, I don't know, it's orange/red/green) and I have to say the quality of this book seems a bit sub-par, in terms of presentation.
I agree with this to some degree, but please hear, well, read me out.
Eric Lachance wrote:First, the cover of the book looks like a 72dpi JPG, there's compression artifacts everywhere around the words and the design. I would hesitate to buy any book with that sort of obviously cheaply thrown-together look.
I asked for the original image files of the background of the original book, but that was not available to me. So the choice was making a new background (which one?) or work with the image files that I could get a hold of. I chose the latter because it was the way that I could handle with the tools I have available. I am not a graphics artist. I know about the somewhat questionable quality of the cover, but I did not have anything better. Getting something professionally done means spending money that at that point I did not have. The economic downturn didn't just magically pass me by. That said, I translated this book on nights and weekends whenever time was available on a 0$ budget.
Eric Lachance wrote:Second, I started to read the first chapter and it's almost unreadable. Not that the text is not good, but the presentation, frankly, makes me want to puke. Double-interline paragraphs with large fonts, almost no spacing between the paragraphs, it's a big wall of text on each page that makes it hard to read, and even harder to get back to if you pause for a second to look somewhere else.
There are three points to this issue:
a) I am not a professional translator and English is my second language.
b) I adhered as much as possible to the original wording, especially in the beginning, later in the book I too a wee bit more freedom to make it read better. That was a decision that I made during the process of translating. Keep in mind, I did not write this book from scratch, it is a translation.
c) In order to have color images everything had to fit on 250 pages. That is the limit that CreateSpace sets. I first opted for b/w images but found that due to resizing screen shots looked like a washed out t-shirt where even I couldn't make out anything despite knowing what is supposed to be shown. After finishing the translation and nicely formatting everything I was way over the 250 page limit. I had to squeeze the square peg through the round hole and this is the result. Am I happy with it? Not at all, but unfortunately the sky was not the limit.

Eric Lachance wrote:It almost seems like this was a PDF that was printed, and was originally meant to be as much information you could possibly cram in a small space, but then decided that the larger the book, the better - so you made the text and spacing larger.
Indeed, it is a PDF that gets printed by CreateSpace. This was the easiest and least expensive means of publishing this book. I could have sent this to professional publishing companies for consideration, but the process for this is expensive, time consuming, and very difficult. I looked into this and found that this just doesn't work out for me.
In regards to the spacing, I don't share the same hatred. I find the spacing to be acceptable, but yea, things can always be better. Spacing and layout are also due to the 250 page limitation. Having a smaller format does not allow for more pages and a smaller format also makes the larger screen shots even smaller. So you are saying the font should have been smaller and the spacing less? That would cram even more text on each page. You claim you already think there is too much text on the pages.
Eric Lachance wrote:Frankly, however decided on the style of this book would have a big advantage on reading something like "Creating reader-friendly books", or the Chicago Manual of Style or something.
Ah, the US writing styles....at least you didn't mention APA style, Chicago is OK. BUT, this is supposed to be a technical book, not a dissertation for a PhD. As mentioned above, the goal was to keep it as close to the original as possible. German (European?) writing styles are different and that probably shows in this book as well. I find most papers written in the US styles to be unreadable, especially the APA format. Other places, other customs. The book is also not intended to be read cover to cover, which is why some chapters may come across as repetitive.
I did plan to have the book professionally edited, but that, too, comes not for free. I did have it reviewed by a native speaker and we spent endless hours mincing words and rearranging sentences, always going back to the original and trying to keep it as closely aligned as possible. Did you ever translated a book and worked through an editing process?
Eric Lachance wrote:Oh... and when you open the cover it says this was created with OpenOffice 3.1... isn't Flare good enough or user-friendly enough to actually write a book on using it to create documentation? That's the laugh of the day! Really now! Edit: just re-read previous comments. I understand why OpenOffice was used... but I don't think it's a valid argument. If Flare isn't good enough to write documentation on itself, then maybe it shouldn't be sold at all?
As mentioned in earlier, I started that way and found that I quickly got confused (making changes in the book project rather than the test project and such). That had nothing to do with Flare not being capable of handling this although at the time I started (which was about two years ago) PDF output in Flare was not the way it is today. Aside from that, OOo is an excellent tool and I see no reason not to use it. If you think that OOo is laughable and they may not have used it. MS Word crashed when loading the document. Maybe it would have been less offensive to some if I didn't add this note in. I also could have just lied and said I did it with Flare, can't really tell by the output.

The entire project was by far more work than I ever anticipated. It was the first time I did this and finishing this project while working full time, switching jobs, moving, have MadCap release new versions of Flare, and have some basic form of family life was difficult. I promised I will translate it, I did the best I could, and I did it with the tools and means I have available. If I could have invested several hundred bucks to get things done by pros to make the book turn out better, I would have done it. Although the sales so far are a pleasant surprise it will take a while to break even. I'm not getting rich of this. I also find the price of the book too high, but the price is about as low as I could set it without having to pay for each copy sold (which CreateSpace doesn't allow anyway). I also signed up for a paid subscription to offer the lower price, otherwise it would have been around 70$, which would be just plain insane.
Is this book the best thing since sliced bread (or frozen pizza, whatever you prefer)? No, it is not. Does it have some production quality issues? Yes, it does. Was it a very difficult and taxing task to get this done? You betcha! Am I proud of it? I definitely am. Would I make better decisions next time? Yes, for sure. Will there ever be a next time? I am not so sure about that, maybe when the kids moved out and I am an old geezer with too much time on my hands. This project was biting off more than I could swallow, but I did it anyway, otherwise it would not have been translated at all.
I am sorry that you think the book is just rubbish and may work to keep a shelf from wobbling. I have reasons why things happened the way they did and I made the best decision I could at the time. If you don't like any of my reasons then I cannot change that. It is what it is and I wish it would have been a bit different at times.

David
Eric Lachance
Sr. Propeller Head
Posts: 127
Joined: Thu May 13, 2010 11:51 am
Location: Montreal, Quebec, Canada
Contact:

Re: New book: Creating user-friendly Online Help

Post by Eric Lachance »

David,

I understand that you had little budget to go with and that may explain some of the limitations. Be honest though, even for a non-graphic artist, re-creating this cover is trivial at best. It's not complex graphics, it's just shapes and lines and probably should have taken less time to re-do than Figure 1 :P

As for the spacing and text... again I'm not saying that the text itself is bad. My points are all on presentation, not content. If you look at page 2-3 (Terminology) for example, that's where it's very obvious - it's a 2-page wall of text with no quickly discernable divisions. The spacing between paragraphs is almost the same as the spacing between each line of a paragraph.

This of it this way: If your text was one point smaller, if your interline was have been a little smaller, you could put a little more space between each paragraph, and perhaps it would be much more readable. One example of what your book could have looked like is the "Single Sourcing" book by Kurt Ament (which is in the recomended reading section of the madcap website).

As for content... As far as I've been able to read without getting turned back by the walls of text, it's actually very good. I do have to congratulate you on actually doing the work, publishing the book and getting it to sell! It's more than I can say for myself (though it's in the works for our own product suite in the future)

Perhaps in a second edition... I'll do the cover for you, deal? :P
Eric Lachance
Technical Trainer
Objectif Lune Inc.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

Deal!
There is a small oops at the end of the book that I noticed recently, one of the empty pages is in the wrong spot and it should be easy to change. It will be a while before I can revisit this (recently moved again into a "new" house, still a lot of remodeling left) and maybe it is worthwhile to wait for the next Flare version to see where additions or changes are necessary. For example, anything in regards to DITA is not in the German original, but Petra and I found it important enough to have it in the English version. Those few pages are not translations, but brand new text.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

After some long time I finally figured out a way to somewhat easily convert the printed book into an ebook for Kindle. Easy, but not cheap. Before I invest into this option, who would be interested in having the book on the Kindle? I cannot tell you how well it would work out, because I do not have any ereaders nor do I have any experience with them.
Let me know.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

At long last, now this book is also available as eBook. See here:
http://www.amazon.com/Creating-user-fri ... B005XB9E3U

Hope this helps out those who are interested, but can or do not want to buy the paperback version.
Grant Hogarth
Jr. Propeller Head
Posts: 5
Joined: Tue Nov 22, 2011 11:39 am

Re: New book: Creating user-friendly Online Help

Post by Grant Hogarth »

Question: which option pays the most to the authors? :lol:
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

Either one pays, but not as much as I'd wish. The most money make others.
sdcinvan
Propellus Maximus
Posts: 1260
Joined: Wed Aug 21, 2013 11:46 am
Location: Vancouver, Canada

Re: New book: Creating user-friendly Online Help

Post by sdcinvan »

It was interesting and educational to read about your challenges with translating and publishing this book. I imagine that many of the Flare challenges have long since been resolved via Flare updates.

I think many of us would love to hear more about your experiences with working with publishing organizations... perhaps some best practices, etc.? Love to hear more. :-)

BTW, any chance of an update for this book?
Shawn in Vancouver, Canada
Main tools used: Flare 11.x, InDesign, Google Docs, Lectora, Captivate.
Report bugs: https://www.madcapsoftware.com/feedback/bugs.aspx ▪ Feature requests: https://www.madcapsoftware.com/feedback ... quest.aspx[/i]
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: New book: Creating user-friendly Online Help

Post by RamonS »

My only experience with publishing is with CreateSpace and this one book. I did think about publishing more, but that means writing more and I just don't have the time. For that reason, there will likely be no update. When I translated I added the DITA section and a few other things, so the English version already contains more than the German original, but adding more and keeping up will take a lot of time when doing it right. Others do tech writing for a living, for me it is currently only a hobby. That said, the book is intended as introduction and explains the basics with Flare being the tool of choice for showing how to implement the various parts. The fundamentals didn't change and for that reason a lot of the book contents is still current and applicable. And the interest in this book is still strong. Thanks to everyone who is still buying! :D
Post Reply