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

Link to the book #1574

Merged
merged 1 commit into from
May 12, 2023
Merged

Link to the book #1574

merged 1 commit into from
May 12, 2023

Conversation

mike-burns
Copy link
Contributor

Thank you for your years of service, GETTING_STARTED.md. You're in a better place now.

Thank you for your years of service, `GETTING_STARTED.md`. You're in a
better place now.
Copy link
Contributor

@sej3506 sej3506 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍🏻

@mike-burns mike-burns merged commit 4a37cb6 into main May 12, 2023
@mike-burns mike-burns deleted the link-to-the-book branch May 12, 2023 18:46
@jasonkarns
Copy link

I'm a little worried that the docbook is going to make finding things harder.

As a realistic example from a few seconds ago, we searched the getting-started file for invocations of association to see how to provide a trait. Cmd-F association found all examples in the page.

The same approach in the docbook is broken because of the book's multipage format. 😞

@mike-burns
Copy link
Contributor Author

@jasonkarns that's my biggest concern, too.

Does the book search handle that? https://thoughtbot.github.io/factory_bot/?search=association

@jasonkarns
Copy link

jasonkarns commented Jun 21, 2023

@mike-burns perhaps, but TBQH, i'm not going to know (or look for) bespoke search functionality in each doc site of the multiple and various tools we use. Cmd+F is ubiquitous.

I don't really have good suggestions :/ overriding Cmd+F to use custom site search is fraught with peril. but ignoring it and requiring one use site-specific search is also a frustrating UX.

And in most cases with FB in particular, i don't want a list of search results. i want to bounce very quickly from result to result. jumping back and forth between a result and the search results listing would be... not good (even presuming one used the site-search).

I guess I'm just being salty that my cheese was moved. :D

If i'm being honest, I'll probably continue to use the single-page getting started until it actually disappears or becomes wrong.

Unless! there's a way to have the docbook generate a single-page listing? seems that would be the best of both worlds? (thinking back, whenever I browse GNU tooling docs or IETF RFCs, etc I usually opt for the single-page format, not the multi-page. typically for this same Cmd-F use case)

@jasonkarns
Copy link

jasonkarns commented Jun 21, 2023

So now i'm just carrying on, but i did see the new docbook site has a print view, which is one giant page. https://thoughtbot.github.io/factory_bot/print.html

If i'm making nitpicky requests, it would be fantastic if that single-page view were linked somewhere. As it stands, hitting the print icon and dismissing the browser print dialog isn't too terrible. i'll probably just bookmark that single-page url. But making that page a "first class" option seems like a decent compromise?

@mike-burns
Copy link
Contributor Author

Good call on the print view, I'll add some more links to it so people can jump straight there.

If mdBook ever adds single-page output, I'll generate that from CI so we can have that option.


Also, thanks for understanding. I feel the same frustrations you do regarding Ruby docs (Rails, factory_bot, and other special cases, plus rdoc for each library ...) and I hope we as a community can find a better way forward.

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

Successfully merging this pull request may close these issues.

None yet

3 participants