Ideas for improving DevGuide

[Ilmari Lauhakangas]

On 8.3.2022 14.05, Hossein Nourikhah wrote:
> 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

Probably Mike's idea for a programming language selector will help here.

> 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

I'm not sure if this is an issue as the focus is not in a printed 
version. Some years ago when the format was discussed, having it in the 
wiki was the consensus.

> 7. Images and diagrams are not editable

This can be changed in the future with Mermaid.js for the UML and for 
the others maybe with SVGs having Draw files as the source. The Mermaid 
conversion task might be a good easy hack. I wouldn't rush this and 
would keep it as low priority for now. This includes finding a 
JavaScript dev to improve Mermaid and I've been working on this for over 
2 years (the devs keep giving up...)

> 8. We need ways to create a PDF version
>      * Manual changes may be necessary

Again, I don't know if we need this, but an interesting option is 
PagedJS, which I have experimented with some time ago.

https://pagedjs.org/

I found a couple of recent extensions & tools for MediaWiki that use it:
https://titipi.org/wiki/index.php/Wiki-to-pdf-manual
https://github.com/Appropedia/appropedia-pagedjs

Ilmari