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

Split up the README into webpages #888

Closed
jyn514 opened this issue Jul 13, 2020 · 4 comments · Fixed by #942
Closed

Split up the README into webpages #888

jyn514 opened this issue Jul 13, 2020 · 4 comments · Fixed by #942
Assignees
Labels
A-newcomer-roadblock Area: A problem that isn't a bug, but makes it harder for people to contribute C-enhancement Category: This is a new feature C-technical-debt Category: This makes the code harder to read and modify, but has no impact on end users E-medium Effort: This requires a fair amount of work

Comments

@jyn514
Copy link
Member

jyn514 commented Jul 13, 2020

Currently the README is six screens long. We regularly have people asking questions in #docs-rs that are answered in the readme, and it's hard for me to find things even as the person who wrote most of it. We should split it up somehow; mdbook is markdown, simple, and we could host it ourselves on docs.rs (split up https://docs.rs/about/ as well? most of the content there is duplicated in the readme right now).

Inspired by rust-lang/rustup#2396.

@jyn514 jyn514 added A-newcomer-roadblock Area: A problem that isn't a bug, but makes it harder for people to contribute E-medium Effort: This requires a fair amount of work C-technical-debt Category: This makes the code harder to read and modify, but has no impact on end users C-enhancement Category: This is a new feature labels Jul 13, 2020
@jyn514
Copy link
Member Author

jyn514 commented Jul 13, 2020

This would also be a natural platform for #752

@Nemo157
Copy link
Member

Nemo157 commented Jul 13, 2020

It might be possible to do this directly in our code instead of using mdbook, to avoid having to either check-in generated files or integrate mdbook into the build process.

As a quick sketch, we could define the table of contents via an enum, setup a docs.rs/about/:page handler that matches down to an enum variant, then include_str! a markdown file for each variant that gets rendered into a template that also includes a generated table of contents from the enum.

@jyn514 jyn514 changed the title Use mdbook instead of the enormous README Split up the README into webpages Jul 13, 2020
@jyn514
Copy link
Member Author

jyn514 commented Aug 6, 2020

Now that #924 is merged, I think we should remove most of the readme in favor of pointing to /about.

@Kixiron
Copy link
Member

Kixiron commented Aug 6, 2020

A lot of the forge can probably be deduplicated there as well

@jyn514 jyn514 self-assigned this Aug 6, 2020
@jyn514 jyn514 mentioned this issue Aug 6, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-newcomer-roadblock Area: A problem that isn't a bug, but makes it harder for people to contribute C-enhancement Category: This is a new feature C-technical-debt Category: This makes the code harder to read and modify, but has no impact on end users E-medium Effort: This requires a fair amount of work
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants