[webkit-dev] WebKit Documentation

[Brent Fulgham]

> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev <webkit-dev at lists.webkit.org> wrote:
> 
> 
>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev <webkit-dev at lists.webkit.org <mailto: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/
> 
> I’ve been working on 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.

Ryosuke: Your document is outstanding, and is a large part of the content we pulled into the current repo. I don’t think we view this as a competition; rather we are trying to host a collection of Markdown content in a common repo that does not have to be pulled and synced with WebKit source and tests. This provides a lower bar for people interested in contributing documentation as they do not have to download and sync Gigabytes of WebKit code to write documentation.
> 
>> 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.

We discussed this internally, but today’s message is the first discussion on this repository that we’ve opened on the webkit-dev mailing list. We wanted to convince ourselves that the tool worked well, and was easy to use, and could produce documentation output that would be useful for Apple engineers. That is not the only intended audience for this work, but is the origin of this effort which we wanted to make available to others to use and contribute to.

Those of us who have worked on WebKit for some time can easily remember the many discussions over the years about documentation efforts of various types. Lots of people have strong opinions, but few ever contribute despite their opinions of the right way for the work to be done. You are obviously part of the group that has contributed heavily, so I am sad that you do not seem to like our approach.

> 
>> 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.

DocC is one way of processing the Markdown content in this repo, and one that works well with Xcode since it creates output that matches Apple documentation style, and an output archive that can be consumed and used within Xcode search features.

There is nothing stopping an interested party using any of the other available Markdown-to-HTML tools to process the data in a way they prefer, much like WebKit sources can be built by Xcode, Visual Studio, and Make.


>> 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 other than to allow existing C++ code to call into Swift API: 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.

DocC is not a requirement to use or participate in this work. It’s simply a “port” of the documentation that works for our needs. If others prefer to “build” output documentation from Markdown using a different tool set, they are welcome to contribute those build commands and instructions.

Our goal is to accumulate all relevant and open source documentation related to WebKit in this repository so that we can generate searchable documentation. We would also like this to be accessible and searchable from the web.

Thanks,

-Brent

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