Problems: Redundancy between docs.webkit.org & wiki; confusion; PR costs. Solution: Move/centralize all doc sources into one canonical place where project committers/reviewers can directly land changes without needing to raise PRs

[sideshowbarker]

Problems

• Some docs content in the wiki is similar/redundant with docs.w3.org content.
• Having similar docs in multiple places is confusing for users. Which place is canonical — which should they use/trust?
• Some (potential) contributors reluctant/unwilling to do PRs to add/change docs.webkit.org docs; time/trouble costs.
• Many (most) contributors more likely to contribute to the wiki; wiki contributing is easier + quicker (lower costs).
• Without totally disabling wiki, no way to prevent new wiki content redundant with existing docs.webkit.org content.

Goals/requirements

• Have only one place where all the canonical doc sources are stored, only place where contributors make changes.
• With no need to raise docs PRs, contributors can make canonical docs changes directly (i.e., the way the wiki works).

Solution A: Move everything into the wiki

• Take all existing content from wiki & docs.webkit.org, merge/centralize it into the wiki (i.e., the wiki’s backend repo).
• Serve/deploy/publish centralized content to both docs.webkit.org and wiki as the single “canonical” project docs.

Solution B: Move all to docs.webkit.org repo, but allow commits with no PRs.

• Take all existing content from the wiki and merge/centralize it into the docs.webkit.org repo.
• Change docs.webkit.org repo settings so project committers/reviewers land changes directly, with no need to do PRs.
• Serve/deploy/publish all centralized content from docs.webkit.org as the single “canonical” project docs collection.
• Completely disable the WebKit wiki (via the https://github.com/webKit/WebKit/ repo settings).

---

Rationale

A single centralized/canonical repo for the docs:

• Eliminates all current redundancy.
• Avoids causing user confusion about which is most up-to-date & canonical — because it’d all be the same content.
• Makes contributing as easy as possible for all potential contributors; lowest barriers, lowest time/trouble costs.
• (Former) wiki contributors get the new benefit of their contributions automatically showing up at docs.webkit.org.
• Gives potential contributors significantly more incentive to take the time to contribute quality docs content.

---

Questions/arguments against + answers/rebuttals for those

---

Q: If all content sources are moved to the wiki, what use would anybody then have for docs.webkit.org?

A: Good question. One good answer: docs.webkit.org does already exist and is a cool URL and Cool URIs don't change. Also, docs.webkit.org gives the project a way to brand/theme/skin presentation of the docs in whatever way the project chooses — rather than being restricted to the simple/limited common theme/branding GitHub’s wiki engine produces.

---

Q: docs.webkit.org uses a hierarchical structure (with subdirectories), but the wiki is a flat structure with just a single top-level set of pages, and no subdirectories — which doesn’t allow hierarchical structure.

A. True. So part of the process of moving/migrating the existing docs from docs.webkit.org back into the wiki would require flattening out the directory structure, so all the pages are maintained as a single flat set in a top-level directory.

But there are still some ways to impose a kind of hierarchical structure. One of those ways it use a structured naming convention for page names. See https://github.com/validator/validator/wiki for example, which uses a naming convention where some page names are prefaced with Output » while others are prefaced with Service ».

With such a convention, you can even have multi-level hierarchical names like Service » Input » file upload. And so in, the Pages sidebar of that page (and other pages), the wiki automatically hierarchically sorts the page names::

---

Q: Somebody would need to do the actual work of setting it all up.

A: I’d be personally willing to put time and work into making it happen.

---

Implementation notes (complications to do deal with)

Here are some details about how the centralized solution should be implemented/deployed:

Make the entire docs/ subdirectory into a git submodule

The most-straightforward way to implement the proposed solution would be to change the entire existing https://github.com/WebKit/Documentation/tree/main/docs directory into just being a git submodule from the https://github.com/WebKit/WebKit.wiki.git wiki repo.

For better docs.webkit.org site navigation, add in an extra mkdocs module, or move to new tool

Serving content from the (flat-structure) wiki at docs.webkit.org introduces some additional complications around page-titleing and sorting and such that would benefit from having some finer control over navigation features for the site.

While it’s true the core mkdocs engine itself doesn’t provide good control over site navigation and page titleing/sorting in navigation, etc. — there are some third-party plug-ins that do much more. Probably the best is mkdocs-literate-nav

Or else it could also be worth investigating whether it’d be more productive to move to another tool that’s more closely suited to publish-a-website-from-a-GitHub-wiki needs.

---

[cdumez]

I do not wish for docs to be in a repository. Keeping docs up to date is already hard enough, if we add extra friction for updating (forking & making a commit / PR) then it will only be worse. For this reason, I want a wiki and I am using the wiki.

[cdumez]

I do not wish for docs to be in a repository. Keeping docs up to date is already hard enough, if we add extra friction for updating (forking & making a commit / PR) then it will only be worse. For this reason, I want a wiki and I am using the wiki.

As a result, I would object to this proposed solution:

Take all existing content from both the wiki and from docs.webkit.org, move/merge/centralize it into a single git/GitHub repo.

[cdumez]

@cdumez Understood — but to be clear: The wiki docs are already in a repository, at https://github.com/WebKit/WebKit.wiki.git.

It’s just that when you make changes to the wiki via the wiki editing frontend, what happens on the backend is that you cause commits to be made to that git repository.

As a result, I would object to this proposed solution:

Take all existing content from both the wiki and from docs.webkit.org, move/merge/centralize it into a single git/GitHub repo.

To be more clear about my proposal and to put it in terms of the wiki: What I’m proposing is:

• The wiki content stays exactly where it is, and you continue to be able to edit it exactly as you do now.
  So, no changes at all in docs workflow for you.
• The current contents of the repo for docs.webkit.org are what get moved/merged into the wiki
  So you’d then additionally be able to change/fix to any of that content directly at the wiki, instead of doing PRs.
• To make docs changes, you’d no longer need to do any PRs anywhere — you just do it all through the wiki.

And please see that I’ve now added the above list as as Goals section in the issue description, and I’ve updated the title to:

Solution: Move/centralize all doc sources into the wiki, serve both docs.webkit.org and wiki from same sources

Does that all make the proposal now sound more acceptable?

To me yes. I agree it'd be great to have documentation in a central place, as long as I keep wiki editing.

[mdubet]

I do not wish for docs to be in a repository. Keeping docs up to date is already hard enough, if we add extra friction for updating (forking & making a commit / PR) then it will only be worse. For this reason, I want a wiki and I am using the wiki.

FWIW, it's possible to edit the documentation repository directly from the web browser in markdown (but you don't get to see the html result) example : https://github.com/WebKit/Documentation/edit/main/docs/index.md

[sideshowbarker]

I do not wish for docs to be in a repository. Keeping docs up to date is already hard enough, if we add extra friction for updating (forking & making a commit / PR) then it will only be worse. For this reason, I want a wiki and I am using the wiki.

FWIW, it's possible to edit the documentation repository directly from the web browser in markdown… example : WebKit/Documentation/edit/main/docs/index.md

@mdubet Yes, thanks much for pointing this out. Also worth mentioning here: all the https://docs.webkit.org docs have an “Edit this page” pencil icon which, if you click it, takes you to the GitHub UI for editing the doc directly in your browser.

But that said, the repo settings as currently configured have the main branch set to be a protected branch — so, once you make edits to the page, you can’t land (commit) them right away, but instead need to click a button to raise a PR.

However, it’s completely possible to change those settings so that project members with commit/push privileges actually could commit directly to the main branch without needing to raise PRs. Or else, the settings could be updated such that the branch which changes from the GitHub UI would get landed (committed in) ine would be a ”staging” (or something) branch that a project owner subsequently would merge into the main branch (for publishing to docs.webkit.org).

(but you don't get to see the html result)

True — but there is also a Preview button which when you click on it shows you a preview of a rendered version of the markdown — and that rendered preview is almost exactly like what you when editing a page in the GitHub wiki.

So @cdumez, can you please take 5 minutes or so to try this:

1. Go to a page like https://github.com/WebKit/Documentation/edit/main/docs/Deep%20Dive/MemoryManagement.md and trying making some throwaway/test edits to it directly in your browser.
2. Push the Preview button there to see rendered output of your changes right away.

…then, that’s basically just like editing a doc at the wiki, right?

The only difference is that to actually land your edits, you then need to push the green Commit Changes… button,
when then currently will cause a PR to be raised (and then you need to go through the PR review process to land it).

However, what’s possible is that the setting could be changed such that when you pushed that Commit Changes… button, your edits would land immediately — without you needing to go through the PR process.

If the settings were changed such that you do that — that is, make docs edits directly in your browser and land them right way, just like you can now at the wiki — would that workflow work OK for you?

It would basically be just like how you make changes to the current wiki — you’d just be doing it in a different place.

[mcatanzaro]

I do not wish for docs to be in a repository. Keeping docs up to date is already hard enough, if we add extra friction for updating (forking & making a commit / PR) then it will only be worse. For this reason, I want a wiki and I am using the wiki.

This used to be my opinion too -- I think I mentioned pretty much exactly that when docs.webkit.org was first proposed -- but now that the docs website exists it's kinda too late. A lot of effort went into this website, it does the job, and having one place for our docs is by far the most important consideration. E.g. we can't rightly expect new contributors to follow the new smart pointer guidelines because our smart pointer documentation makes no mention of them.

I would just add Chris directly to the project so he doesn't have to use pull requests. I think most developers are probably happy to use pull requests, but let's not require them.

The GitHub web UI workflow for committing to docs.webkit.org is really close to GitHub wiki; you edit in Markdown, and have live preview. The only flaw I see is that docs pages currently link to the toplevel directory instead of the actual page of the content on GitHub. That creates a small amount of friction that doesn't exist in a wiki, which would be nice to get rid of.

[mcatanzaro]

Also, since both projects use Markdown, moving content from wiki to docs website is mostly going to be a matter of Ctrl+C Ctrl+V. So that, at least, is not a very huge change.