[webkit-dev] WebKit Documentation

[Ryosuke Niwa]

> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev <webkit-dev at lists.webkit.org> wrote:
> 
> Documentation is an important part of any open source project, especially for a larger project like WebKit. Being able to ramp up during the onboarding process, reading up on architectural decisions, and learning how to perform common procedures are all features the documentation should tackle. WebKit has a large set of documentation already, but it is scattered around a wide range of platforms (Trac, GitHub Wiki, markdown files in the code, Git commits, etc...), and some of the information is out of date.

This ultimately feels like this situation:
https://xkcd.com/927/ <https://xkcd.com/927/>

I’ve been working on https://github.com/WebKit/WebKit/blob/main/Introduction.md <https://github.com/WebKit/WebKit/blob/main/Introduction.md> for the past couple of years, and I’d would have preferred to have a collaboration rather than a competition here.

> A few months ago, I started working on a new documentation solution based on the DocC documentation framework.

Was there any discussion as to which documentation framework should be used? I’m personally not familiar with DooC documentation, and I’m  surprised that such an important decision was made unilaterally without much discussion on webkit-dev.

> I have already ported a large section of Trac, all of the GitHub Wiki, and all of the non third party markdown files in the code over to this platform.

I’m not certain if there is a community wide support that this is the right tool to migrate all our documentations. I for one certainly object to the use of DooC as the primary documentation tool.

> I have tested this on macOS and Linux and have found it works extremely well. (Windows should be able to use WSL2 at the moment, while a few remaining issues get sorted out). The only dependency for this project is a recent installation of Swift.

Previously, we’ve rejected Swift as a general purpose programming languages in WebKit: https://lists.webkit.org/pipermail/webkit-dev/2014-July/026722.html <https://lists.webkit.org/pipermail/webkit-dev/2014-July/026722.html> other than to allow existing C++ code to call into Swift API: https://lists.webkit.org/pipermail/webkit-dev/2021-June/031882.html <https://lists.webkit.org/pipermail/webkit-dev/2021-June/031882.html>

As such, I don’t think we should require having a functional Swift toolchain as a requirement for contributing to WebKit or its documentations either.

- R. Niwa

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20220920/133845d6/attachment.htm>