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

Create an Appendix #207

Open
micokoch opened this issue Nov 6, 2024 · 2 comments
Open

Create an Appendix #207

micokoch opened this issue Nov 6, 2024 · 2 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@micokoch
Copy link
Contributor

micokoch commented Nov 6, 2024

Following @zkamvar's suggestion (#206), I am considering building an Appendix section for the hubverse website. There are two matters for which I want feedback:

  1. Where should it live? I think it should be the last section, but I can also see an argument for including it before the Code of Conduct.
  2. What should be included in the Appendix? Here are my suggestions:
    • Key Definitions (currently in Overview)
    • Abbreviations (currently in Overview)
    • Presentations (currently in the User Guide)

Please let me know if I should proceed.

@micokoch micokoch added the documentation Improvements or additions to documentation label Nov 6, 2024
@micokoch micokoch self-assigned this Nov 6, 2024
@nickreich
Copy link
Contributor

nickreich commented Nov 13, 2024

My few thoughts about this specific idea and a few other things that this all brings up:

  • In general, I think the TOC bar on the left-hand side of the site is too long. Could we have the main topics be collapsed by default? (note: I opened default to collapsed TOC sections on docs website #210 to address this)
  • I think the presentations should not be buried in the Appendix. I like these in the overview.
  • I'm less convinced that "key definitions" should be buried in the appendix, as this is an important set of concepts that people should probably look at not as an afterthought.
  • I agree that abbreviations feels "appendix-y" but if it's the only thing there, then is it worth a high-level TOC header?

@zkamvar Did you have a more specific vision of what the appendix would include and where it would live?

@zkamvar
Copy link
Member

zkamvar commented Nov 13, 2024

WRT to the TOC bar, that's something I will look into. The answer is: it ultimately depends on the future of the documentation.

I think the presentations should not be buried in the Appendix. I like these in the overview.

Ironically, these are literally the last items in the user guide at the moment.

The "key definitions" and "abbreviations" are both categories of "Reference/Information" (in the diataxis framework). Neither of these pages are great for reading straight (they are the pantry items of documentation... you go to them when you need them).

The problem with the "key definitions" at the moment is that they are presented without context, so they feel more like a glossary of terms.

I think it's worthwhile to hold off on this issue until I have painted an outline for #211

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
Status: Todo
Development

No branches or pull requests

3 participants