Writing books for third party plugins and programs (Yes or No?)

Should books be written for third party plugins and programs, and what would this look like? Recently, Olivier asked this question, thanks Olivier! I am looking for comments from the Xojo forum community.

Writing books for third party products, like plugins, programs, and other products has been asked, and I do not have a clear answer. Perhaps this is a good time for the community to discuss this topic. Currently, books are only written for Xojo products or plugins that are shipped with Xojo. Here are some thoughts on this topic, and I invite others to add comments.

  1. Writing books for plugins
    There are many good plugins that are created by Monkeybread (Christian), and other common plugins for Xojo are also created by Einhugur (Bjorn), Bkeeney (Bob), and others. The Xojo community is friendly and writing a book for one company may (might?) provide a competitive advantage. One of the many ways to treat everyone fairly is to make book-writing services available to all.

  2. Costs
    There is a cost to writing books, which is time, knowledge of Xojo, creating sample programs, and almost always finding bugs. Should the cost be part of the plugin cost: a) purchase both the plugin and book at the same time in the same package, or b) keep the plugin and book separate. My initial thought is that this would be negotiated between the plugin maker and me for each plugin, size of book, etc.

  3. Updating
    With new and great additions to Xojo and the various Operating Systems, there will always be updates. How often should updates be performed? Possibly only on major revisions, or is one book only needed until there have been several changes to the program?

  4. Digital format
    Books are currently in PDF format which can be read on almost any desktop and portable device. Is there another common format which is needed? When experimenting with other formats, the books literally needed to be rewritten to meet formatting guidelines, specialized programs had to be used that created these books. Some formats did not support pictures, which makes it very difficult to show a concept or idea. Is there a widely used format that is needed, other than PDF?

  5. You
    The whole purpose of writing a ‘I Wish I Knew How To…’ book is to help you, the people of the forum, Xojo programmers, and others who I kindly get private emails. What do you prefer? Examples and books on programming are an issue with every programming language. Jokingly, some of the C++ programming books are more complicated than the language itself. Do you like books to come with the plugin (or program), or would you prefer to purchase them separately? It seems that many products don’t have a book and good books take time to write. Should the books be in a specialized bookstore like Xojolibrary.com or should they be listed on Amazon, maybe both?

I am sure that there are other topics I have missed and thanks for your thoughts!

Feel free to write a book if you like about our plugins.

But it’s a big difference if you do this on your own or whether you get paid by us for writing.
And if you write something, I’d of course promote that book to our users.

I have some of your “I Wish I Knew…” books and they’re very good.

Plugins should come with good documentation, unfortunately that is not always the case. I am a firm believer that having someone other than who wrote the plugin or software should write the manual/book. It provides more of a user perspective rather than developer perspective, which is heavily biased and influenced through the development process. The developer thinks the docs are great, but that’s viewed through their eyes, not an actual user.

In the case of Excel, reading your book was more efficient than wading through all the Microsoft docs. I’m sure they think their documentation for Office Automation is great, but that’s viewed through their lens. That’s why third party books have a market, they distill the documents no one wants to read and provide value.

I think MBS plugins are excellent, but I think some additional documentation would be a benefit. They probably have a large enough install base to make it worth it and maybe a co-arrangement or bundle option from MBS with book and plugin at a discount would be beneficial to both.

Love your books Eugene! I think I’ve purchased every one of them and have recommended them whenever I get the chance. They are a valuable part of the community experience.

You raised some good questions. Here’s my first pass and feel free to ask followup questions either online or off.

  1. Definitely a competitive advantage for the product you write about. BUT, there’s nothing stopping anyone (including me) from writing my own version or hiring you to write one for us. So YOUR service is writing and that’s a pretty unique service to this community.

  2. Negotiate with the Xojo developer. Personally, I’d help defray some of your initial costs for a nice comprehensive guide to our products. If I’m helping pay for development I would expect it to be part of my sales package (with cut to you). If I’m not paying up front then all the sales should go to you and are between you the buyer.

  3. Major updates would be a paid update. Maybe a dot release as readers find mistakes is free.

  4. I think PDF is good enough.

  5. I think it would be awesome if you could get them in both XojoLibrary and on Amazon since every book about Xojo in the Amazon listing helps the overall exposure to the language. It then eliminates the inevitable “There’s nothing on Amazon so therefore so why use Xojo?” argument I often hear from prospective clients.

[quote=419573:@Eugene Dakin]

  1. Writing books for plugins
    There are many good plugins that are created by Monkeybread (Christian), and other common plugins for Xojo are also created by Einhugur (Bjorn), Bkeeney (Bob), and others.[/quote]

I found the docs with the monkeybread plugins hard to use… The examples are helpful but it is hard to get an overview that way. The individual plugins have a HUGE range of completely so one book for all teh MBS stuff likely does not make sense.

That said i think individual books on the things like the DynaPDF, ChartDirect an ImageMagic plugin would be best… Then maybe some of some of teh other utilities organized by category in one or multiple books would be best.

In general I find the Einhugar docs much more helpful than MBS. The docs combined with the examples are good enough for me in most cases, though the PDF plug-in might benefit from a small book when one not is not that familiar with PDF way doing things under the hood.

Don’t know about Bob’s stuff.

  • karen

Thanks for your comments Christian. Yes, your right that there is a big difference between writing a book on my own or being paid to write the book. As Bob mentioned, you could hire someone to write your own plugin books. Another part would be ownership of the book - if you were to pay for the book then you would own it. If I were to write the book and rely on income from book sales, then I would own the book.

Good thoughts Christian!

Well, if each book contains a list of other titles on the end, one book promotes the others.

But first you decide if you want to write on your own choice or you want to be hired for writing.
If hired, we would pay and the book would be free to users. But I have no idea what it costs.

On the other side if you write and publish, we could promote it to our users or buy copies to give away.

This is a good point Joseph, as I found the same aspects that you mentioned. When I write a program then the documentation focus on the program is different. Like most people, once I am familiar with a topic, then I tend to (mistakenly) believe that everyone knows the topic as well as I do - which is not the case. Thanks!

Thanks for your comments Bob, and you raise good points when talking with a fellow writer/blogger. By the way, your blogs are great and I read almost every one!

  1. Yes, your right that any creator of a program and/or plugin can, and usually does, write documentation and its in the form of a help file. Chuckle, I look at multi-million dollar corporations like Microsoft and Mac with the vast amount of online documentation, yet there are many books written on various topics to help users. If Microsoft and Mac still have books written on their language, then I guess there is still room for improvement.
  1. I agree that negotiating with the developer is likely the way to proceed. Some developers may not want documentation, while others may want complete control. There are always many options that are available for negotiation.

  2. Paid updates for major releases follows a common software release model, which makes sense and is probably the easiest to track and maintain.

  3. Yes, PDF seems to work for most people and devices.

  4. I have heard the “There’s nothing on Amazon…” comments before, and I’ll likely be having the book listed on both Amazon and XojoLibrary. Marc with XojoLIbrary and Norman before him, have been a long-time supporters and I look forward to working more with XojoLibrary in the future.

I agree that one large encyclopaedia of information is likely not the way to proceed. Smaller and more concise information is likely easier for the user to read and easier for me to maintain. Chuckle, I had one request where someone wanted a book on “Everything Xojo”. Although it is a noble request, I doubt that I will be able to write it all. Its been 8 years since my first Xojo book, and there are many more books that can be written.

the size of the book is likely going to depend on the options available for a plugin.

Thanks Karen!

I believe that it would be a great help if there was some documentation template for the plugin developers.
This standard documentation would make reading for the buyers of the plugins much easier.
A book by you @Eugene Dakin could be the first step in the that direction. :wink:

I would definitely buy a book that provides genuinely helpful documentation for MBS.

1 Like

I think the Xojo community is too small to make writing a book worthwhile. Also your book will be very soon out of date and updates are necessary. This all cost time and therefore also money. There where a few books in the past, but they where not maintained after their initial release.

About the format, PDF alone will not do any longer. I read the books I buy on my ereader. Really PDF is the worst format to use on an ereader. It is always fixed and does not reflow which is necessary to nicely read on an ereader.

Eugene, you are thinking the wrong way about the formats. First create the epub, then you can convert it to PDF. Stay away from Scrivener, Jutoh is much better. Jutoh is a little bit more difficult but once mastered it pays off. If you want to read more, take a Ian Stables course on Udemy. Going from epub to PDF is easier than you think believe me.

What you do in Jutoh is writing your ebook in epub completely in Jutoh. Then when that is finished you export to ODT (LibreOffice) where you can create your PDF. With Jutoh it is also possible to convert from PDF to epub but it is more cumbersome than the other way around. I will convert the latest API book to epub for reading on my ereader. Also forget about DRM, they only frustrate your legal customers, the others remove the DRM in an instant. I cannot understand why so many people here, stick with the proprietary PDF format. It has its uses for printed books but in this age of ebooks, its highdays are over.

I like your books very much, they are very good written and informative. But in my opinion the plugin makers should write good documentation. I once bought Monkeybread plugin, but because of the very poor documentation it was a waste of money because I never could it work because of the poorly written documentation.

If I can make a suggestion, write a Xojo book just in epub format and maintain that. A printed book will become outdated too fast.

Hope this helps.

Chris

Hi Chris,

Thanks for the honest information, I greatly appreciate it. There are so many self-proclaimed products that say they can handle the words, pictures, and formatting of books, but usually fail. I’ll take a look at Jutoh (quite honestly, I have not heard of it before), and see how it holds up to a moderate book of 500 pages or so.

Yes, I completely agree that electronic books are the way to go. Version 2.x of the declare book had 8 updates, and then there is now version 3.0, which will be getting more updates. Electronic books make it much easier to update. I usually have one book printed in hardcopy for myself, just in case a total meltdown of my backup hard-drives happen.

I agree that the creators of the plugins are usually the best people to write documentation, and its not limited to plugins or programs. It seems to be in almost all areas such as Engineering, Chemistry, and of course Computer Science and Engineering. For some reason there just doesn’t seem to be enough time to create the documentation.

I am definitely going to look at Jutoh. Thanks!

I think Eugene having a remote backup somewhere is more important than a "dead tree version’ which will not stand a fire incident in your office.

Well, the Xojo world is small, but let’s say Eugen writes a decent book and offers it for $20, we promote it to something like 2000 MBS customers and only 10% buy it, it would be $2000 of revenue. Not sure if that is worth writing it…

of course such a book doesn’t need to be $20, but could be $50.
Or better a series of books for different topics, so you can sell each customer several titles…

I will definatelly buy Eugene’s book. About Jutoh, I also would like to add that they have very good customer support. There is no forum but they have a kind of email list. If you put a question, the developer Julian, responds very quickly.

You can contact him by email with your questions before you buy Jutoh. Jutoh has two versions, the normal one and the Plus one. For such a powerfull program, you are gonna be surprise about the price. The Plus version (I have) let you access the HTML and Javascript. The normal version does not. Also worth to note is that you can also compile ebooks in the Mobi format for Amazon.

If you think on the market alone epub/mobi will open for you, I really think you are gonna get much more readers for your books. Smashwords, Barns & Noble, Amazon to only name a few. When you use Smashwords, they distribute your book automaticly to those others.

The learning curve of Jutoh is a little steep, very much worth the efforts. Also the produced epub file is very good quality. You can create your book into a wordprocessor (docx) or you can directly write it Jutoh. Writing directly in Jutoh has the advantage that you do not have to worry about synchronization. That is also the route Julian advised me to follow (he and his wife also write their books directly in Jutoh).

I tried other epub creation software (Scrivener, Kotobee Author, Ebook Maestro Pro) but finally came accross Jutoh in Augustus this year. I never looked back to the others since I use Jutoh.

Eugene, I am sure when you can deliver epubs, your readers base will grow much larger. You write and compile for epub/pdf based on that one source.

Have a nice New Year.

Chris

Talking about a book(s) for MBS Plugin(s),one hard decision to take is Â… one (very large book) or many smaller; and in the later case, what to put in each books to make them appealingÂ…

Well, I could provide a list of topics:

  • DynaPDF
  • ChartDirector
  • SQL
  • XL (Excel)
  • Java
  • AVFoundation
  • GraphicsMagick
  • Barcode

for example.