Crowdfunding to support improving Uno/IDL documentation?

I’d like to help make major improvements to the documentation for the Uno library and/or the IDL reference. Could I use crowdfunding to support this?

— TLDR —

Several years ago I changed my personal office suite from Microsoft Office to LibreOffice. I haven’t regretted that decision, but a constant thorn in my side has been macros. I had a substantial collection of MS Office macros that I had come to depend on. I planned to port (or rewrite) them to LO, and hoped to be able to switch from Basic to a “real” language (Python).

I’ll spare you the saga of all the pitfalls I encountered trying to learn how to write LO macros, and focus on the single most vexing one: the lack of good documentation for the Uno API and the IDL reference. Whether I’m trying to understand how an existing macro works, or write a new one from scratch, I always seem to hit a brick wall when I try to understand the various classes/interfaces and their members.

I have a strong motivation to do something to improve the documentation, rather than just complain about it. I have the skills and experience to do it, but it’s a huge task. I can’t justify donating enough time to it to make a difference, and I’ve read that the Document Foundation employs very few engineers. I think there’s enough demand for this work that I could defray my time investment through crowdfunding, but I have no idea whether this would violate any rules or norms within the LO/TDF community.

So… Is this an idea I should pursue?

Thank you for your feedback,

– Ed Stauff

TDF employes several engineers, so I think you could first try acting as a manager to us and also other volunteer documenters :slight_smile:

One big task is updating the developer’s guide, originally from 2009: LibreOffice Developer's Guide - The Document Foundation Wiki

Have you been in touch with ScriptForge developers and documenters?

Edit: see also the ESC meeting minutes from this week:

Q: one help page per UNO command?

You have my support for getting the API more usable. I actually made a patch in that direction. May be there are a need for a guideline in documenting so everybody is happy.

https://gerrit.libreoffice.org/c/core/+/149590

Cheers
Olivier

I agree with you that documentation about scripting in LibreOffice can be improved, mainly for those starting with Basic and Python programming in LibreOffice. One main challenge is that there are many layers when it comes to LO scripting. We could even call it LibreOffice Scripting Stack =)

For instance, someone starting off with LO scripting today would have to learn a few complex topics:

  1. The UNO API (including its architecture, the concept of interfaces, services, commands, enumerations, structs, etc)
  2. Organization of scripts within LO (user scripts, application scripts, document scripts; where they are stored) both in Basic and Python
  3. Dealing with listeners (in documents, dialogs, etc)
  4. Learning how to access the UNO API from Basic and Python scripts
  5. Learning how to dispatch UNO commands
  6. Learning supporting libraries, specially ScriptForge that aims at simplifying scripts
  7. Create and deploy extensions with Basic and Python modules (alongside dialogs)
  8. Create and implement interfaces (this is super advanced topic)

I wish some day we’ll have a unified resource (maybe a LO Scripting Guide) that introduces all of these topics in an integrated manner. Today you can find information about all of them, but they’re all spread throughout various sources, which complicates things for those starting to learn how to create scripts in LO.

As for IDL documentation, have you read this?
https://wiki.documentfoundation.org/Documentation/DevGuide/IDL_Documentation_Guidelines

Thank you for your responses.

ilmari asked:

Have you been in touch with ScriptForge developers and documenters?

No, not yet.

rafaelhlima asked:

As for IDL documentation, have you read this? [IDL_Documentation_Guidelines]

I’ve seen it, though I haven’t read all of it yet.

I think what I’ll do next is draft an outline of the improvements I’d like to see, and would work on if I could get funding, and post it here to get more feedback.

Regards,

– Ed

Perhaps this guide (quite old) could serve as a reference. I found it by chance on the Web.
In Pdf version at

And in odt version with a link that downloads it directly.
https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwiv_dnFk6GBAxVkVKQEHSK9CxIQFnoECBUQAQ&url=http%3A%2F%2Flaurel.datsi.fi.upm.es%2F_media%2Fdocencia%2Fasignaturas%2Fsi_bio%2Fpub%2Flo_basic.odt&usg=AOvVaw2oS_73Gxuo2g6Mqv41H4vY&opi=89978449

I don’t quite understand the licenses that come with it but it appears to be written or reviewed by members of the documentation team.
I have tried to search for it in the wiki files but I have not found it.
I also don’t understand why it is not published nor has it continued to be updated.

Sorry my bad English.