Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 20, 2022, at 1:52 PM, Brent Fulgham  wrote:
> 
>> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
>>  wrote:
>> 
>>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>>> mailto:webkit-dev@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.

Who are these people who want to contribute to WebKit’s documentation yet 
doesn’t already have a clone of WebKit repository? I just can’t think of people 
who would fit that description.

There was a reason behind why the entire Introduction.md was written as a 
single markdown file though. Namely:
Reader can look up unknown terms right away in the same page using browsers’ 
find feature
Let reader be aware of things they are unaware of.

(2) is particularly important because many people who are new to WebKit often 
don’t know what they don’t know. This is why, for example, memory management 
section appears towards the beginning of the document and the information about 
adding IDL files is immediately followed by the discussion of JS wrapper 
lifecycles. With these information now split across multiple files, it’s easy 
for people to miss out on critical information. In the ideal world, people 
won’t be adding or editing IDL files before they understood how JS wrappers are 
managed because not knowing the latter is a sure way of introducing subtle GC 
bugs.

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

Right, it’s why I wrote Introduction.md in the first place.

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

Okay but then which variant of 

Re: [webkit-dev] WebKit Documentation

[Brent Fulgham via webkit-dev]

> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
>  wrote:
> 
> 
>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>> mailto:webkit-dev@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

___
webkit-dev mailing list
webkit-dev@lists.webkit.org

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 20, 2022, at 6:04 AM, Michael Catanzaro  wrote:
> 
> On Tue, Sep 20 2022 at 01:16:53 AM -0700, Ryosuke Niwa via webkit-dev 
>  wrote:
>> 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.
> 
> This Introduction.md is great work (I've learned a lot from it), but it's 
> also getting pretty long for a single document. At least, it significantly 
> exceeds my attention span. We could present this same info better if we split 
> it into multiple pages.

Yeah, I agree. I wanted to keep the document searchable; putting them all in a 
single document lets us use browser’s “find” function. GitHub wiki pages are 
searchable so splitting into multiple pages isn’t an issue there.

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Michael Catanzaro via webkit-dev]

On Tue, Sep 20 2022 at 01:16:53 AM -0700, Ryosuke Niwa via webkit-dev 
 wrote:
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.


This Introduction.md is great work (I've learned a lot from it), but 
it's also getting pretty long for a single document. At least, it 
significantly exceeds my attention span. We could present this same 
info better if we split it into multiple pages.



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Konstantin Tokarev via webkit-dev]

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

Also, Markdown is not the only format supported by GitHub. It's also possible to
use AsciiDoc, POD, reStructuredText, or any other format listed in [1] in any
file of main repository or in wiki, and it will be rendered to HTML when 
browsing
online.

[1] https://github.com/github/markup/blob/master/README.md#markups

-- Regards,
Konstantin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 2:58 PM, Michael Catanzaro via webkit-dev 
>  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 
, 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

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>  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.

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

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 4:48 PM, Fujii Hironori via webkit-dev 
>  wrote:
> 
> Why not double-down on WebKit Git repository?
> The closer the document is to the source code, the easier to keep them 
> up-to-date.
> We can modify both the source code and the document in a single commit 
> through our review process.

The fact documentation is separated from code is a feature, not a bug. We don't 
want to make updating documentation a contribution requirement. Just like unit 
tests, this sort of thing can significantly hinder our willingness and 
capabilities to do large scale refactoring, renames, etc...

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev