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

Rework on documentation guides #5893

Merged
merged 3 commits into from Jul 10, 2019
Merged

Conversation

@davidfischer
Copy link
Contributor

@davidfischer davidfischer commented Jul 8, 2019

  • Significant improvements to the custom CSS/JS guide
  • Broke out the guides into Read the Docs and Sphinx/MkDocs guides
  • Small grammatical and copy improvements

I'll probably do more work on more of the guides slowly but surely. The key things to improve on are to make sure that the right words that people would search in google for are present on the page and it make sure to explain why in addition to how.

Screenshot

Screen Shot 2019-07-08 at 4 33 11 PM

Here's the current guides page for comparison.

- Significant improvements to the custom CSS/JS guide
- Broke out the guides into Read the Docs and Sphinx/MkDocs guides
- Small grammatical and copy improvements
@davidfischer davidfischer requested a review from Jul 8, 2019
@davidfischer davidfischer changed the title Rework on guides Rework on documentation guides Jul 8, 2019
@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jul 9, 2019

Actually, I'm going to update this as it looks like Sphinx made this quite a bit easier in Sphinx 1.8.

Loading

@humitos
Copy link
Member

@humitos humitos commented Jul 9, 2019

Side comment: "Sitemaps: An SEO tool for documentation" is not a guide since the user can't do anything with that. It's more like a Read the Docs Feature. Maybe we should move it there.

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jul 9, 2019

Side comment: "Sitemaps: An SEO tool for documentation" is not a guide since the user can't do anything with that. It's more like a Read the Docs Feature. Maybe we should move it there.

That's the next guide to refresh on the calendar. There's no longer a directory of "features" in the documentation. I think we should build it out into an SEO guide that also has other things like how to set <meta> tags and setting the canonical URL. If you want to work on it, let me know 😄. Otherwise I think that's next up in a few weeks.

Loading

Copy link
Member

@ericholscher ericholscher left a comment

Good changes. Just one nit and a thought, but not something necessarily to address now.

Loading

@@ -1,5 +1,5 @@
Build PDF format for non-ASCII languages
========================================
Sphinx PDFs for non-ASCII languages
Copy link
Member

@ericholscher ericholscher Jul 9, 2019

Choose a reason for hiding this comment

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

non-ASCII should probably be something else.

Suggested change
Sphinx PDFs for non-ASCII languages
Sphinx PDFs for languages other than English

Loading

Copy link
Contributor Author

@davidfischer davidfischer Jul 9, 2019

Choose a reason for hiding this comment

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

Technically it's non-latin languages. How about "Sphinx PDFs for Unicode Languages" or "Sphinx PDFs for Non-European Languages"?

Loading

Copy link
Member

@ericholscher ericholscher Jul 10, 2019

Choose a reason for hiding this comment

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

Yea, I didn't know the best way of putting it. I'm fine with Unicode, as it seems the most correct. 👍

Loading



Sphinx & MkDocs how-to guides
Copy link
Member

@ericholscher ericholscher Jul 9, 2019

Choose a reason for hiding this comment

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

I do feel like we're making the guides harder to find when we add more nesting to the TOC's. I can almost never find the development docs now, since it's nested under 2 levels and really hard to ctrl+f to find. I think we might hit a similar issue here with folks wanting to go to our docs and do ctrl+f then search for PDF. I don't know the best way to solve this though :/

Loading

Copy link
Contributor Author

@davidfischer davidfischer Jul 9, 2019

Choose a reason for hiding this comment

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

Since the guides were already not on the home page (anymore) I don't know if ctrl+f would really help in this instance.

In general, I believe that most users are finding pages by searching google and getting a direct link rather than going to our docs homepage first.

Loading

Copy link
Member

@ericholscher ericholscher Jul 10, 2019

Choose a reason for hiding this comment

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

Yea, definitely -- but I'd like to support both flows reasonably well. Perhaps promoting search into a landing page-style box in the main content would help here. I need to think more on it.

Loading

@davidfischer davidfischer merged commit f198ce0 into master Jul 10, 2019
1 check passed
Loading
@delete-merged-branch delete-merged-branch bot deleted the davidfischer/guides-restructure branch Jul 10, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants