Research and reflect: Would Gitbook improve the user experience for docs contributions? What else could we use?

[stichbury]

I'd like to make it easier for contributors to make changes to documentation. Hell, I'd like to make it easier for the team to make documentation changes, and I'd like to make it easier for myself too.

Right now, if you spot, say, a typo on a docs page you have to look at the page name in the URL, fork or clone the Kedro main branch, and branch off it, navigate to the file in docs/source open and edit it. Then sign your commit, push to the remote and wait for the whining to start from the CI. Fix anything you've broken, like the whitespace or a DCO, and re-try. Etc. Until you get the green tick of acceptance from CI and can initiate review and merge.

I'd love to see this made simpler for people that don't do it all the time. I recently saw a Gitbook demo and it looks much better for contributors, while still giving power to manage PRs and veto changes to the code owners.

I wonder if this is a possible way forward for Kedro docs, at least markdown docs, but I appreciate it's not the only option.

So this is a ticket to generally look at how we could streamline the process of docs contributions and potentially this bleeds into a more holistic overhaul of the docs toolchain. However, it's not a priority until other milestones are addressed, such as #2600 for subprojects and #2932 for Algolia search improvements.

[astrojuanlu]

I think if we could get a DCO exception for docs + Add a "Edit on GitHub" button that actually took users to the .md file in question that would already be a massive improvement 👍🏽

[stichbury]

Would be good to get some steer from LF on how other projects manage the DCO for docs contribs, as it definitely slows down the process. Particularly if they're not that familiar with what we expect, so it takes a fair bit of back and forth and may even put some people off doing another PR. I like the idea of just hit a button, fix a line of text, and commit it, if that's any possibility without massive amounts of changes to our tooling.

[astrojuanlu]

We agreed to reach out to LF to have some insight about this.

In addition, looks like some IDEs like VSCode allow configuring this automatically, see microsoft/vscode#83096 (comment)

[astrojuanlu]

Also, it's unclear to me if we have this enabled, but there's definitely a way to ease the contribution process for web commits https://github.blog/changelog/2022-06-08-admins-can-require-sign-off-on-web-based-commits/

[astrojuanlu]

Yeah just spotted this myself when tweaking a text file from the GitHub URL

[astrojuanlu]

Reached out to LF AI & Data.

[astrojuanlu]

I confirm that, after enabling web signoff for kedro-plugins, now I see this on our own repo

On the other hand, we got permission from LF AI & Data to disable the DCO bot for non-code repos.

[stichbury]

The range of responses from LF about whether we could disable DCO on our framework repo was somewhat unsatisfactory. But since the final response was "no", I guess that's the one to take.

DCO doesn't just affect docs contributions, I don't see the upheaval of moving docs into a separate repo just to disable it as paying off across the board for contributors. If we were to consider such a step, I'd also suggest we review a bunch of other changes to improve docs contributions, such as a switch to Gitbook, which was the purpose of this ticket initially.

So that was a useful detour but ultimately this is still to be addressed and still a lower priority than other changes. I'll leave it open pending a period for reflecting on docs tooling, which won't be until 2024 at the earliest.

[astrojuanlu]

FTR, I've enabled the "sign-off web commits" on this repo too. Let's see if that improves things.

[astrojuanlu]

De-prioritizing this for the time being.