Link rotting and GitBook organization of pages

[contraexemplo]

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]

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]

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.

[jaskiratsingh2000]

Redirecting will cause more load on server side and would be less feasible on client side due to time dependency. We need to think different to this. What do you think ?

…

On Sat, 12 Oct 2019, 2:04 pm Alanna, ***@***.***> wrote: 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. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#37?email_source=notifications&email_token=ACOBHKZE7SIGTOV4JFUT3YLQOGD2VA5CNFSM4I7G5J6KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBBZX3Y#issuecomment-541301743>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACOBHKYFDJILSTUVFKBYZBLQOGD2VANCNFSM4I7G5J6A> .

[contraexemplo]

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

[Betree]

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]

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

[jaskiratsingh2000]

Ohkay fine. We can go ahead with this

…

On Mon, 14 Oct 2019, 5:57 pm Anna e só, ***@***.***> wrote: I agree! I'll keep adding links to the .gitbook.yaml file. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#37?email_source=notifications&email_token=ACOBHK4GPTCXNSFWGNXCTM3QORQURA5CNFSM4I7G5J6KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBEOK2I#issuecomment-541648233>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACOBHKY5CG5YTTXO2HGC443QORQURANCNFSM4I7G5J6A> .

[alanna]

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]

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