Making contributions smoother #20

kousu · 2021-10-25T20:54:36Z

Gitbook released a new version with a lot of changes (without warning) that needed some quick action on our part to reset user permissions to get things working again. This has motivated some internal discussions about how to work with it.

In particular, the "Edit on Github" button is currently broken; it seems that it's supposed to be supported

but it's disabled for us for some reason; maybe because we were migrated instead of created fresh and are now in some sort of legacy mode.

More broadly, since the summer we've been in an uncomfortable limbo, maintaining our docs with two UIs: this repo, and with app.gitbook.io. The new Gitbook version is especially pushing its WYSIWYG editor, making it more like Notion.so or Google Docs and I think this is the best moment to summarize the tension and settle on one workflow.

kousu · 2021-10-25T21:42:06Z

Cons of Gitbook

It's lock-in SaaS software.

Gitbook 1.0, still online at https://github.com/GitbookIO/gitbook, was a nice static site generator, like sphinx, with a lot of aesthetically pleasing defaults. It's best feature was that its input was markdown (so, nearly plain text) and that it could be self-hosted.

I originally supported using Gitbook because it promised to be "just markdown". But that's not what v2 is

"a GitBook specific versioning system" means "a proprietary format that only exists on our servers". It's probably some hodge-podge of JSON. This explains why Flakey gitbook sync #9 is such a problem, and why export/import to Github is only going to get worse, not better, with time.

This is not a future-proof format. It is not something we can archive. So long as their github integration is working we can export and recover if we need to, maybe, but we've already used a bunch of unportable gitbook-specific features like {% tabs %} that will be a pain to redo the day that Gitbook pivots.
It subjects our users, and us, to surveillance capitalism

The first clue to this is the GDPR cookie warning they have:

In fact I can't use it in my normal browser because clicking a link will often trigger

I debugged this a little bit and one trigger is blocking Firebase; it seems that Gitbook needs to contact Firebase once, but it doesn't actually store its content there because if I allow it once then keep it blocked it renders content fine. So is it setting some sort of tracking cookie, and without the tracking cookie I can't read the content at all? What could justify that?

Here's all the sites it needs to contact, just to render a wiki:

It clearly doesn't actually need all that, because fully disabling javascript, even 1st-party javascript, renders fine:

But the fact that they feel entitled to make these requests on my behalf bothers me.

I make a habit to reject these consent banners whenever I can, and I don't think anyone else should have to feel pressured into accepting them just to get their work done, or even just to explore what we're about non-committally.
It's really javascript heavy, even for read-only use.

See the previous point: it mysteriously overlays an modal error message sometimes without explanation. If javascript is off entirely it never does, but if it's partially on then it refuses to let me use it, sometimes, when it feels like being obstructive.

Similarly, I can't even log in to it if I am blocking third party trackers. Other sites manage to do OAuth without javascript handling the auth tokens; I don't know why Gitbook needs it? If I try it with tracking protection on, I just get

The in-page sub-table-of-contents used to not render with javascript disabled

but in this one case they seem to have improved, and gone towards using universal HTML instead of javascript.

So: v1 was a static site generator. v2 has regressed to leaning heavily into javascript.

Not all of us can keep up with the latest expensive macbooks that startup devs all code on! Ease of UI is important for accessibility, but another important dimension of accessibility is the resource drain it demands.

For me, the main reason keeping me away from editing Gitbook is how many hoops it makes me jump through: disable all my blockers, close any other tabs like Google Docs or Messenger that are also DHTML heavy so I don't epuise my RAM.
It's an unstable product.

The surprise permissions glitch and the broken Edit on Github banner aren't the first bugs we've had with them. Flakey gitbook sync #9 continues to be a problem, and with them pushing their live editor I predict the git side will continue to get less and less maintenance. This is a symptom of v2 being produced by a startup searching for product-market fit, and losing their v1 roots as a solid tool.

Another bug is that everytime we reuse an image, like all the social media icons on https://www.neuro.polymtl.ca/team, it duplicates each. See all the dupes here: https://github.com/neuropoly/neuropoly-docs/tree/601e159/.gitbook/assets

Another bug is that it gets confused when pages are moved around: "Deleted" and moved pages still exist intranet.neuro.polymtl.ca#7; even right now https://github.com/neuropoly/neuropoly-internal-docs/tree/82dea057ecda6a3430821edbaaf9d48411e64f32/mri-coils is an old version of https://github.com/neuropoly/neuropoly-internal-docs/tree/82dea057ecda6a3430821edbaaf9d48411e64f32/mri-scanning but it doesn't appear in the WYSIWYG editor anywhere so there's no way to know it's there, falling out of date.

Another bug is that, bizarrely, despite supporting an internal {% embed %} tag, it does not support Google calendar embedding despite this being an ancient and widely spread feature of the public internet: Embed google calendar intranet.neuro.polymtl.ca#10. 💢 It seems {% embed %} is outsourced to a company that's literally called https://iframe.ly and I guess they just..don't do Google? Or something?

For documentation, we should want something boring that we know we can rely on, archive, and restore as needed. That doesn't mean it has to be unattractive, there are many static site generators with very pretty themes.

For obvious evidence of its instability, their v1 repo, which is still pinned on their Github

has a dead link to their migration guide

to https://docs.gitbook.com/v2-changes/important-differences that just 404s now.
It requires extra accounts.

Another reason I originally supported switching off DokuWiki was because account creation on Dokuwiki was slow. @alexfoias runs all over our platforms doing admin and sometimes things just pile up, so it would take some time to grant wiki accounts to newcomers. Switching to Gitbook allowed us to have people self-inscribe with the Gitbook Team Invite Link, and allowed people to use Sign In With Github to avoid remembering another password.

But the accounts on app.gitbook.io are still their own thing. It means in addition to managing https://github.com/orgs/neuropoly/people, we need to spend admin time onboarding, offboarding, and auditing https://app.gitbook.com/o/-MYD1C9e-AHCd61VhjhF/settings/members, and it means time manually synchronizing permissions between the two apps (e.g. Ainsleigh was still the owner on Gitbook until a couple days ago, despite not working for the lab for a month+ now). It means people need to write down in their password manager whether they used a password or Sign In With Github with Gitbook -- but in practice I bet most of us have just forgotten and need to be reminded "try sign in with Github" when it comes up; and if that fails, they need to bug one of the admins to help them figure out what step is missing.

So switching to Gitbook hasn't reduced the account overhead, in my opinion.
It's another language to know.

I also supported moving away from DokuWiki because, I thought, on top of it being slow to get an account, it was slow to learn its wiki markup. Markdown and RST are the dominant markup languages now, and everyone in the lab has to know them to work on our projects, but having to know a third just for the wiki was a big ask.

By being able to write our lab manual in markdown we save brain space.

But they're not really a markdown renderer anymore (see above). Instead they're really their own format, that can only be edited with their WYSIWYG editor. That makes it another third language; just instead of a plain text language, it's a visual and kinetic one, with its own quirks.

kousu · 2021-10-25T21:56:39Z

Pros of Gitbook

It's table of contents in the default theme is very readable

This is great:

the inline ToC is great
People can self-onboard.

I still think the admin side is at least, maybe more, complicated with Gitbook than Dokuwiki, but at least people don't need to wait on us to grant them accounts when they join.

jcohenadad · 2021-10-26T01:08:31Z

Thank you sooooo much for the thorough evaluation, @kousu . This is amazing. All the arguments you have raised make sense. Do you have suggestions of alternative products (keeping in mind the specs that we are after, ie, "easy" editing)?

I would like to hear some feedback from the rest of the team also.

kousu · 2021-10-26T18:26:08Z

Alternative(s) to Gitbook

I think we should start with the constraint that we keep this repo alive and use the Github editor for editing the wiki. Then we only have the one set of accounts and permissions to manage.

their editor isn't live or WYSIWYG but it has Preview one click away:

We should make sure to leave this repo unprotected so everyone in the lab can edit without having to go through PRs. (but people can still use PRs if they want feedback).

Then, as for reading and using it, I have two ideas:

Just use Github

I think in the short term we could go replace our A record with a HTTP 301 redirect and/or an HTML <meta> redirect that bounces people from https://neuro.polymtl.ca -> https://github.com/neuropoly/neuropoly-docs/. namecheap can do this, or we'd have to have polyit point neuro.polymtl.ca back at some internal server that we could control. In the even shorter term we could just erase all the content on Gitbook and put a big "Please Click here".

Aesthetics

The default Github markdown renderer is fine IMO. It renders text and images and it's elegant enough. We can't control it or put our logo in the corner, but in a pinch it's serviceable.

Primary Table of Contents

Instead of a sidebar, it just has a directory hierarchy:

This isn't great but it's also not the worst, especially since the folder names are sensible.

Secondary Table of Contents

Github has a per-page ToC generator, as of sometime last year:

It doesn't render on pages that only have one heading:

and it's a little bit unobvious, but it's there.

Edit on Github

Github, of course, has an edit button built in

Hosting

Hosting is built in because Github renders markdown files in its web UI by default.

Instead, use Sphinx

We use sphinx in all our other repos, e.g. https://github.com/spinalcordtoolbox/spinalcordtoolbox/tree/master/documentation/source renders to https://spinalcordtoolbox.com/, the same for shimming-toolbox.org/, https://axondeepseg.readthedocs.io/en/latest/, etc. We can use it here too.

sphinx supports markdown (via a plugin) so we don't need much rewriting. Mostly we just need to add the sphinx config file, and also rewrite Gitbook's SUMMARY.md as sphinx toctrees.