Break apart README into guides?

[baweaver]

Noticed that trying to load the README on any mobile device or device without a lot of bandwidth is going to lag out or crash a browser. Would it be possible to segment the README into cross-linked subguides, rather than having the entirety of the information present in it?

[AndyObtiva]

I am surprised that today's cell phones couldn't process a long web page as effectively as a desktop web browser.

That said, back in the day, I did break down the README of Glimmer DSL for SWT when it grew to a similarly ginormous size.

You are welcome to make this contribution if you like by breaking apart the README into guides. If you do, please follow my example in Glimmer DSL for SWT, where I nested the guides (sections of README) under /docs/reference: https://github.com/AndyObtiva/glimmer-dsl-swt/tree/master/docs/reference

Otherwise, if I do find the time myself to do it before you do, I would do the breaking apart myself, but don't count on it anytime soon since I have many other competing higher priorities.

Thank you for reporting.

[rubyFeedback]

Personally I actually like having a big "page" in the README as it is more efficient for me to just search and jump to a relevant part. I am using the desktop, though, so I understand it is different for mobile users with smaller screens and less resources to use for rendering. Ideally we could have a situation where we can offer both a long page, as well as a "book-like chapter" structure that would allow for more flexibility for displaying content. Would be great if github could offer something like this by default - anyone asked them? That could become a generic feature too since more people could benefit from it.

Andy kind of offers "secondary" information in regards to (and through his) videos, though. I think these are a bit better suited on a smartphone device too, even if the resolution may not be ideal on a small screen, people will probably hear the explanations just fine, and then Andy could link in the videos like in a step-wise tutorial. That may help as some kind of additional documentation. (And perhaps to find the content again at a later time, so adding keywords to the videos perhaps, for people to find it more easily. For instance, I think the second video showed an example for a class-based approach of glimmer usage, which I actually wasn't aware of some weeks before that.)

[AndyObtiva]

@rubyFeedback Just FYI, GitHub already supports a Table of Content feature that lets software engineers jump quickly between sections whether in Desktop or Mobile browsers.

Here is a screenshot of where to find it (I use it all the time; you just gotta click on the list icon on the top-left corner):

[AndyObtiva]

I extracted the example documentation out of the README into separate markdown files (they are linked from the README under Examples though):

• Glimmer DSL for LibUI Basic Examples: https://github.com/AndyObtiva/glimmer-dsl-libui/blob/master/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md
• Glimmer DSL for LibUI Advanced Examples: https://github.com/AndyObtiva/glimmer-dsl-libui/blob/master/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md

This reduced the README size from 11557 to 2698 lines of code.

As a result, the crashing issue in iOS has gone away. I can browse the Glimmer DSL for LibUI GitHub project page on an iPhone 13 Pro, including the example documentation, without problems now.

I still think the webpage should have worked before on modern iOS devices (like iPhone 13 Pro) given that they now contain processors and memory specs that are comparable to desktop computers. I think it is on Apple to fix this in the future. It is equally on other mobile phone manufacturers (e.g. Android phone makers).

But, for the time being, the problem is resolved by extracting the example documentation out into separate markdown files, even without extracting more guides out. I am keeping the API guide in the README for now, especially given that @rubyFeedback expressed preference for that. If the API section grows too large in the future, I could extract when needed. In any case, this was not a serious issue at all anyways since the documentation concerns desktop development software, so it should be checked on a desktop computer to begin with. Reading on mobile phones is only an extra convenience, which is facilitated again now.

I am closing this issue as a result.

p.s. Don't forget that you can still break out guides and contribute via a Pull Request if you really want more guides. This is an open-source project, so it's a community effort with a two way street, not a one-way closed-source software shop.