Ideas for improving DevGuide

[Regina Henschel]

Hi Hossein,

Hossein Nourikhah schrieb am 08.03.2022 um 13:05:
> Hello,
> 
> As you may already know, with the efforts from Ilmari, DevGuide is now 
> imported as multi-page chapters into the TDF Wiki. There were some 
> performance and formatting problems that are now resolved, or will be 
> fixed soon thanks to Ilmari and Guilhem. Hopefully, we can have single 
> page version of all the chapters soon:
> https://wiki.documentfoundation.org/Documentation/DevGuide

I get only chapters 1, 2 and 3.

> 
> But, other than minor improvements that I am working on, we need ideas 
> for improving DevGuide that may need major changes.

> 2. It discusses multiple languages
>      a. Most of the examples are in Java which is not very useful today
>      b. Multiple languages, from Java to C++ and C# are used in the book
>          * It is hard to follow
>          * It does not work as a reference with the tutorial style of 
> the book

I think, that multiple languages are needed. Especially Java and Basic 
are needed. The examples could be organized dynamically so that the user 
can click on a button or so to get the example in his preferred 
language. And there could be for each language a specific "First Steps" 
chapter.

>          * What is the target audience?
Read first paragraph on start page ;)
The target audience are developers of extensions and developers who want 
to use LibreOffice in background for their own applications.

> 
> 3. Chapters are very lengthy
>      * Chapter 2 is > 200 pages
>      * There are other giant chapters, another 5 chapters with > 100 pages
>      * Average number of pages for the chapters 1-19 is > 80 pages

I see no problem in the length of a chapter. But it should be organized 
in smaller portions than now. Someway in the middle of one page and the 
very small pages in wiki.openoffic.org.
[..]
> 5. The book structure is not optimized for print
>      * It uses hyperlinks instead of pointing to chapters and sections
>      * Several hyperlinks are used that are not visible in print

Nobody wants to print out this guide. But it would be an improvement to 
provide an offline version without the surrounding Wiki stuff in the 
SDK. That could be HTML of PDF.

[..]
> I think removing old stuff, and sticking to C++

I think, for the target audience Java, C# and Basic is more relevant 
than C++.

Kind regards,
Regina