Migrate to gitbook - should we do it? [No]

[hamishwillee]

Summary

The reason for considering a migration to gitbook (or any other docs platform) is that it will improve some of: editing, review, administration, maintenance, scalability, or functionality, without significantly reducing any of the other items.

Gitbook is often suggested as a potential replacement to our current system because it has an excellent content editor and good inbuilt search. The theory is that this will make contributing more accessible.

In summary, it may not be worth it:

• Getting started would be just as hard or harder for most users and reviewing much harder.
• Additional admin of users required. Review not as easy.
• Migration relatively easy but we will lose some features and have to make some compromises - essentially we would not have uORB graphs and things like parameters would have to change to headings in order to be linkable.

We might however consider migrating to it just for rendering, if we're willing to "pay the cost".

We might also do it if enough of the dev team want it - because we can given them more powerful logins and trust them not to merge breaking changes.

What would it look like?

It would look like the image below. You can get some idea of what this might look like from my playpen: https://hamish-willee.gitbook.io/px4-user-guide/

Doc management workflow comparison

The ideal open source editing workflow in an open source community where content quality matters, is one where

• any reader can easily contribute a suggestion for a change and there is no administration cost to the project for the reader to get access
• the change must be approved by a trusted person before being merged. The reviewer should be notified that there are changes and find it easy to determine what the changes are and merge them.

The vuepress/github workflow achieves most of this:

• Every page has a link at the bottom "Edit this page". A user can click that link to be taken to that page to edit.
• The reader will have to create a login if they don't have one - this is easy and requires no work for the project. Editing the page is fairly easy and has a preview.
• The change must be approved by someone in the team. That person is notified and github has excellent change comparison tools.
• New pages and new images in pages are much harder and require use of git, github, local vuepress. In particular git workflows are hard for new users.

By comparison on gitbook there is no way to click a link and be taken to gitbook for editing.
That means the workflow would have to look like this:

• Reader looking at a page, and sees some issue they want to fix.
  • We create a link in the menu to "Contribute" which provides a link for the person to join the gitbook project as an editor.
  • They click the link, join gitbook, find the space, find the page. Only then can they edit it using the fantastic editor.
    • To my mind this harder than working with github for casual users.
• Reviewer does not get a notification of changes in project by email.
• Reviewer eventually discovers change and uses relatively average comparison tools to review the changes.

All that might be worth accepting if the person fixing the page could also add new pages. However they can't without a more powerful login that gives them complete control to trash the space. This is revertable, but a pain.

Upshot it is fewer steps to edit now than it would be on the new system, and the maintenance cost is lower.
However for trusted users it could be much better - because we can give them full powers through the UI and ask them not to merge changes.

Migration

• We can migrate the bulk of the content relatively easily from our current structure to github - as you can see from https://hamish-willee.gitbook.io/px4-user-guide/
  • This required a source fixup for note/tip/warning and youtube formats and also summary moved from /en to root and the links fixed up. Gitbook only generates sidebars for stuff in summary.md.
  • The translations are created by creating a new branch or repo that replaces the summary in the root and reimports the result into a new space. Each translation gets its own branch or repo. This is needed because our translations come via crowdin from the subtree, but gitbook must import summary from root. So we need to recreate the translation in the right structure for import. This could be managed easily with gitbook actions.

So basic migration and translation can be done relatively easily, without even affecting most of our current process for translation.

The problems are features we use that are not supported or not supported in the same way:

• Tables are rendered fixed-column widths and more than 4 columns scroll wide. This means imported tables for things like flight modes, parameters etc. render very badly.
• The only anchors are heading anchors, and possibly only for level 2 and 1 headings. Upshot is that parameters and many other places will need to have their links fixed.
• Javascript not allowed - Uorb graphs will not work

[hamishwillee]

FWIW, I'm less and less inclined to move towards gitbook. It has some nice features, but we have better search, better review tools through github, and better automation. The main value it has is "instant build", which I think we might get via docsify