Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Condense spread-out topics into single-page documents #501

Open
straight-shoota opened this issue Mar 29, 2021 · 1 comment
Open

Condense spread-out topics into single-page documents #501

straight-shoota opened this issue Mar 29, 2021 · 1 comment

Comments

@straight-shoota
Copy link
Member

In the Specification section some topics are spread across multiple pages that should be combined into extensive single-page documents.

For example, the subsection about if clause has seven subpages detailing specific aspects of the language feature.
Most of them are fairly small with just a couple of paragraphs and a code example.

They would comfortably fit into a single document which describes if clauses in entirety. Each detail would still have its own subsection and can be directly linked to. But it's embedded in the larger context of the language feature with its different aspects. The page about case clause for example already covers all aspects in a single document.
User experience is improved because everything about the topic is handled in a single document and you don't have to navigate between pages for reading individual sub-features. The table of contents makes on-page navigation nice and easy.

As a bonus effect, integrating these sub-pages also improves navigability of the menu tree because there's less nested sections. If we can

This picks up an aspect brought up in #384. See Page boundaries for an initial analysis.

There are several section that I would suggest for merging up:

  • if clause section + unless clause (preview)
  • Truthy and falsey values and logical operators (preview)
  • while clause section + until clause (while)
  • Type reflection section
  • Low-level primitives section
  • C bindings section
@Tamnac
Copy link

Tamnac commented Jun 6, 2023

I like the previewed changes, any reason you haven't added them? Only thing is the "truthy and falsey values" page might need renaming, maybe to "logical operations" or something.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants