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

The MBS documentation is not so bad, but it is like the original documentation of the libraries used: there is no real user manual. It is a very synthetic language reference, written not by a documentalist, but by a high-level developer.

Sometimes a few pages or a small booklet would already be very useful to know how to approach the library. When we discover it, but also several months or years later, when we need it again, but we don’t really remember how the library is structured (especially since each library is often completely different in the way it operates and understands the objective).

It would be tens of minutes or hours of savings each time. Once you have in mind the functioning of the library, and everything is clear in your mind, you just have to refer to the official documentation to get details on the functions, it’s happiness!

Of course, at $50 for a little booklet on MBScurl for example, everyone would complain. But the professionals would still buy it, I’ll buy it, because it’s worth the price. Christian is already saving us time with his plugin, all we need now is a real manual. This is a lot of time saved, less stress, better quality code. Writing technical documentation is a real profession that requires both strong technical skills and strong pedagogical skills, it is very rare and valuable.

When you are used to the good quality of Xojo documentation, it is difficult to switch to a third-party library documentation, not only because there is no real manual, but also because it is often a very different operating logic than Xojo.

Concerning the format, I like the basic web, simply with bootstrap for example. It is mobile and computer-readable, universal, easily updatable, you can use automatic translators and other third-party tools that can help, you can copy and paste, etc.

Translated with www.DeepL.com/Translator

As someone who has bought all Eugene’s books, and rebought the latest one, they have been, and continue to be an invaluable source of information. In regards to plugins the market is smaller again so there is a cost implication for an author, but take Chartdirector, I have come to use this more of late and find that myself spending too much time on trial and error in conjunction with the C++ help on the Chartdirector authors site, sample programs as well as some Q&A with Christian all of which takes time. Sometimes example programs are not enough, but Christian’s support is excellent and prompt but should it be necessary to ask simple questions? If there was a book on it that was only 100 pages long and cost me $50 i’d but it and I’d still be better off!

Software manuals are mostly not for reading from cover to cover. If a good e-book or online documentation saves you only half an hour from trial and error it’s worth the money.

[quote=419795:@olivier vidal]The MBS documentation is not so bad, but it is like the original documentation of the libraries used: there is no real user manual. It is a very synthetic language reference, written not by a documentalist, but by a high-level developer.

Sometimes a few pages or a small booklet would already be very useful to know how to approach the library. When we discover it, but also several months or years later, when we need it again, but we don’t really remember how the library is structured (especially since each library is often completely different in the way it operates and understands the objective).

It would be tens of minutes or hours of savings each time. Once you have in mind the functioning of the library, and everything is clear in your mind, you just have to refer to the official documentation to get details on the functions, it’s happiness!
[/quote]

THIS! The MBS documentation is written from the point of view of someone who already knows how to use it, not someone who is trying to understand how to use it. A lot of times my biggest question is “What is this useful for?” Context and rationale are missing.

Absolutely worth it, my time is money. Great idea to make it available library by library.

As to format, PDF is my preferred (if it has bookmarks); I don’t use e-readers. As to software books not being for reading cover to cover, I disagree - I’ve read many cover to cover, and enjoyed them when well-written, e.g. anything by Matt Neumann.

Yeah, that’s really it.

Hi Chris,

Jutoh looks like a very powerful program to create books. I’ll be reaching out to Julian (the creator of Jutoh) to ask some questions about the program. After trying a few scenarios when converting existing books with the Jutoh program, there are some problems that I have seen, and this is likely because of me not being familiar with the program.

Good Points:

  1. Can create many book formats
  2. Conversion from Microsoft Word to Jutoh is good for a few number of pages
  3. The editor is fast when typing and editing in large books
  4. Jutoh can create many different file types
  5. Is inexpensive to purchase
  6. Has many options for editing and creating a professional book

Room for improvement

  1. Conversion from Microsoft Word to Jutoh will require a complete rewrite of large books (like mine)
    a) my initial conversion of a 500 page book has over 3500 errors during the conversion program
    b) formatting is good for about 75% of the information and poor for about 25% of the book
  2. Jutoh does not natively convert to a PDF format and requires another program to create a PDF document
  3. There are formatting issues with the way the PDF is created,
  4. Might possibly need to have two book documents: One for PDF creation and another for Amazon
  5. Conversion to mobi caused a crash of the program
  6. Unable to create an HTML document because of errors

Just for the fun of it, I am going to make a quick 10-page book and then create the different book types and see if Jutoh can format and create the books properly.

Use Windows 10 PDF virtual printer ?

I like books if they are written well. I’m currently browsing through an old REALbasic book by Matt Neuburg. I keep it on my bedside table, and if I can’t sleep, I grab it and browse through it. The book is interlaced with a tad of humour - which is important, I think, for what can sometimes be such dreary subject matter.

Nevertheless, there is always something that I learn from that book before I nod off.

Nor will an “electronic” representation of data stand the test of a random solar flare. . . . . :slight_smile:

So Eugene, YES!!!, keep writing. Teaching others is a noble and great cause, but always keep a “hard copy”.

I would prefer more tutorial like articles on specific things you can achieve with the plugins. Additional explanation to go with the standard classes. MBS Java plugin is something I am finding quite hard to get to work with for example. I would easily pay 5-10 dollar for a tutorial on that…

Hi Emile,

This is a good idea. I tried it and unfortunately it doesn’t print the cover page. Also, I tried printing directly for one of the other successful format types that are produced, and there is no print option. My guess is that book publishers would not want their books being printed out with a PDF converter.

Thanks for the idea.

Yes, this is definitely a classic standard for REALbasic/Xojo and contains many good ideas and thoughts. The only part that needed improvement was that there didn’t seem to be enough example-code. Its almost like there was just information to tease me with the answer, and no solution. The book is a really good read and some sections have really good parts that can be used to this day.

Thanks for the kind words. The reason why I started on the book-writing journey is that I couldn’t seem to find the information that I was wanting for my projects. As I kept creating more solutions and work-arounds, many other people were asking the same questions. The next logical step was to share my work in the form of a book. Chuckle, there is no money in writing, and I think my average hourly wage is about $0.50 per hour. This is likely the reason why documentation is sparse with many languages and programs. Projects are where the money is made to put food on the table, where writing is just a hobby. :slight_smile:

This is a good idea Rutger, thank you for the suggestion! I am guessing that the Java Plugin has many functions, and there would be many programs and tasks that the plug can perform. Great idea!

Chris,

Thank you for this great suggestion. After working with this program in the last day-or-so, then I like what it does and it performs most of the work that is needed for large books. I’ll be purchasing it for the next book so that I can create a PDF/XojoLibrary and Amazon version.

Warm regards.

Eugene,

You are welcome. I am glad that Jutoh is also working for you. Every tool has its learning curve and I agree Jutoh is a little steep and has also some glitches. However, their customer support is great and that compensate for the steep learning curve.

Julian always reply, mostly within hours. He is very helpful and experienced. You can also ask him for features you like to see. It is indeed true, you need LibreOffice (better Word support) for creating PDF’s.

I am using Windows 7 but only compile for epub. I will try to compile one of my books for Amazon, however they are small.

Looking forward for your first ebook created with Jutoh. Maybe in the future you will find the time to create such a comprehensive book as the one of Matt Neuburgh. I am sure it will be a hit because many people in the community are looking for such a resource. An ebook is much easier to maintain and update than a paper version.

Thank you for sharing your knowledge and your excellent books.

Chris