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 rotting and GitBook organization of pages #37

Closed
contraexemplo opened this issue Oct 10, 2019 · 9 comments

Comments

@contraexemplo
Copy link
Contributor

@contraexemplo contraexemplo commented Oct 10, 2019

We had a small incident with broken links, so I figured it would be useful to write a post mortem with my findings:

  • A group of pages called collective will get the following URL: docs.opencollective.com/help/collectives. All belonging pages will follow that naming scheme, i.e. the Creating a Collective page receives .../creating-a-collective.
  • The same will happen with main and subpages. The page Collectives has a couple of subpages. Its URL is also https://docs.opencollective.com/help/collectives. So GitBook ignores the group of pages and only renders the main page and its subpages.

Conclusion: GitBook generates URLs to groups of pages and parent pages with the same URL naming scheme. A parent page and its sub pages has more weight to GitBook than a group of pages.

I suspect something similar happened to The Open Collective Way pages, though they simply disappeared instead of just being broken. On my mirror on GitBook, however, everything worked normally. Maybe it was a bug, maybe it was something else. I'm not sure I'll get an answer on that anytime soon.

Questions:

  • How should we proceed with more aggressive changes? Should I stage them on a GitBook mirror first? GitBook acts up from time to time.
  • There will probably be a couple of broken links on the app as we make changes. Which repository should I search to keep those links up to date? I think I'm able to edit more complex files if the only thing that should be changed are URLs.
@contraexemplo

This comment has been minimized.

Copy link
Contributor Author

@contraexemplo contraexemplo commented Oct 10, 2019

GitBook has a redirect functionality we can use (read more about it here https://docs.gitbook.com/integrations/github/content-configuration#redirects). I'll test it out.

@alanna

This comment has been minimized.

Copy link
Contributor

@alanna alanna commented Oct 12, 2019

Using redirects is probably good practice. However the number of links to the docs from the app and emails is small enough that we can probably also fix the URLs manually if changes are infrequent. I assume we'll be doing some restructuring as part of this docs project but after that it will be relatively stable.

@jaskirat2000

This comment has been minimized.

Copy link
Member

@jaskirat2000 jaskirat2000 commented Oct 12, 2019

@contraexemplo

This comment has been minimized.

Copy link
Contributor Author

@contraexemplo contraexemplo commented Oct 12, 2019

@jaskirat2000 @alanna so replacing every hard coded link on the app, for instance, would be a better strategy?

@Betree

This comment has been minimized.

Copy link
Member

@Betree Betree commented Oct 14, 2019

Redirecting is fine. It's Gitbook's servers, not ours so I'm not worried about server load 🙂 And since they offer the feature natively, I'd say we definitely need to go with the solution.

We'll also need to update the old links on frontend and API, but since we have them in a lot of places (including emails) redirecting is a good safety net.

@contraexemplo

This comment has been minimized.

Copy link
Contributor Author

@contraexemplo contraexemplo commented Oct 14, 2019

I agree! I'll keep adding links to the .gitbook.yaml file.

@jaskirat2000

This comment has been minimized.

Copy link
Member

@jaskirat2000 jaskirat2000 commented Oct 14, 2019

@alanna

This comment has been minimized.

Copy link
Contributor

@alanna alanna commented Oct 15, 2019

Update after speaking with @contraexemplo - we will use redirects temporarily while the docs are being updated over the course of their project. Toward the end when the URLs stabilise, we will update them in the codebase so they point to the new addresses.

@contraexemplo

This comment has been minimized.

Copy link
Contributor Author

@contraexemplo contraexemplo commented Nov 5, 2019

Happy to report that this problem has been fixed here: d187972
Additional discussion on the matter: opencollective/opencollective#2600
Task completed! 🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
4 participants
You can’t perform that action at this time.