[webkit-dev] WebKit Documentation

[Ryosuke Niwa]

> On Sep 19, 2022, at 2:58 PM, Michael Catanzaro via webkit-dev <webkit-dev at lists.webkit.org> wrote:
> 
> Why not double-down on the GitHub wiki? It's very easy to learn to use, and there are edit buttons everywhere so there is no "distance" between the docs and the ability to edit them. The easier it is to edit docs, the better we'll do at keeping them up to date.

One drawback of wiki is that changes won’t be code reviewed. I find that the much of the existing WebKit documentations are filled with outdated, inaccurate, and/or incomplete information, and a part of the reason is because no formal review is done unlike our code. At least in my experience working on https://github.com/WebKit/WebKit/blob/main/Introduction.md <https://github.com/WebKit/WebKit/blob/main/Introduction.md>, I find that code review to be generally helpful.

> I like Markdown, and am OK with editing Markdown files wherever they live, but it's not very likely that I would install Swift and figure out how to build a new project to to see what the result looks like. With GitHub, we can easily preview results live to ensure we're not messing anything up.

I totally agree. In order for this new documentation effort to be successful, contribution needs be as simple & straight forward as possible.

- R. Niwa

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