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

Better discoverability of the book #2195

Open
vilgotf opened this issue Apr 13, 2023 · 0 comments
Open

Better discoverability of the book #2195

vilgotf opened this issue Apr 13, 2023 · 0 comments
Labels
c-all Affects all crates or the project as a whole t-docs A change to the documentation

Comments

@vilgotf
Copy link
Member

vilgotf commented Apr 13, 2023

Twilight publishes a book to https://twilight.rs containing a beginner friendly overview of Twilight and, from 0.15 onwards, Twilight's changelog, but this is not well advertised to users looking at just the GitHub repository (Twilight's Discord server, however, links to it in the #info channel). There's primarily three ways of advertising links in a GitHub repository:

  1. Repository website / link (currently set to an invite link to the Discord server).
  2. Inside the top-level readme (as a banner at the top or in plaintext)
  3. As an environment (the API documentation is linked to this way, labeled "github-pages")

I personally consider the Discord server more important than the book, eliminating option 1. Including it in the readme as a banner is certainly possible, but it's long and crowded with less important information and would therefore likely be passed over. Mentioning the availability of the book and broadly describing its contents in the readme under its own heading is probably the best option, but it's not great for users searching for just the link as they need to scroll down past the root files, banners and logo before proceeding. Creating an environment (named, let's say "book") that links to https://twilight.rs would fix this as the environments are listed under the right pannel.

Additionally, an older version of the book is available at https://twilight-rs.github.io. This should either redirect to https://twilight.rs, like how https://twilight-rs.github.io/twilight redirects to https://api.twilight.rs, or be removed outright. Somewhat related to this, GitHub Pages currently only support one Page/repository which is why the book is published with Cloudflare Pages. We might want to switch the API documentation to Cloudflare Pages too as maintaining one configuration is easier than two. #2194 would then be superceeded.

@vilgotf vilgotf added t-docs A change to the documentation c-all Affects all crates or the project as a whole labels Apr 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c-all Affects all crates or the project as a whole t-docs A change to the documentation
Projects
None yet
Development

No branches or pull requests

1 participant