> On Sep 29, 2022, at 5:26 PM, Jonathan Bedard <jbed...@apple.com> wrote:
> 
>> On Sep 29, 2022, at 4:28 PM, Ryosuke Niwa <rn...@apple.com> wrote:
>> 
>>> On Sep 29, 2022, at 11:48 AM, Jonathan Bedard via webkit-dev 
>>> <webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>> wrote:
>>> 
>>>>> On Sep 20, 2022, at 1:52 PM, Brent Fulgham <bfulg...@apple.com 
>>>>> <mailto:bfulg...@apple.com>> wrote:
>>>>> 
>>>>>> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
>>>>>> <webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>> wrote:
>>>>>> 
>>>>>>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>>>>>>> <webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org> 
>>>>>>> <mailto:webkit-dev@lists.webkit.org 
>>>>>>> <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/ <https://xkcd.com/927/> <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> 
>>>>>> <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.
>>> 
>>> Right now we have:
>>> https://github.com/WebKit/WebKit/wiki 
>>> <https://github.com/WebKit/WebKit/wiki>
>>> https://trac.webkit.org/ <https://trac.webkit.org/>
>>> https://webkit.org/getting-started/ <https://webkit.org/getting-started/>
>>> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
>>> <https://github.com/WebKit/WebKit/blob/main/Introduction.md>
>>> 
>>> Brandon’s solution is designed to replace the first 2, and he has buy in 
>>> from the maintainers of the first two, when his solution is deployed, our 
>>> existing wikis will die.
>> 
>> I don’t think there is a community wide buy-in to replace either 
>> documentations / tools at this point. I don’t think people who happen to 
>> maintain the infrastructure get to have unilateral say on which tools will 
>> get supported or deprecated.
> 
> This is an effort to get community wide buy-in.

Right, and I’m pointing out that as of this moment, there isn’t community wide 
buy-in.

>>>>>>> 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> 
>>>>>> <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> 
>>>>>> <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.
>>>>> 
>>>>> 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.
>>>> 
>>> 
>>> Something else worth calling out here is that contributing DocC compatible 
>>> markdown is similar to contributions to 
>>> https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org 
>>> <https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org> that 
>>> eventually end up on webkit.org <http://webkit.org/>, except that we have a 
>>> nice path to automating DocC deployment (either to GitHub pages or a 
>>> webkit.org <http://webkit.org/> property). We pretty frequently use 
>>> technologies in our services we don’t intend contributors to regularly run 
>>> at desk.
>> 
>> That sounds strictly worse than contributing to Trac wiki or Github wiki, or 
>> even Introduction.md then. Why are we making contribution to documentation 
>> harder than it already is?
> 
> I wouldn’t describe it as “worse”, it’s different. It’s not obvious (to me, 
> at least) that the sort of web-UI editing that GitHub’s Wiki and Trac’s Wiki 
> provides is actually desirable.

GitHub & Trac’s WYSIWYG editors are decidedly better in terms of user 
ergonomics.

>>>>> 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.
>>>> 
>>>> I suggest that we don?t migrate contents of https://trac.webkit.org/wiki 
>>>> <https://trac.webkit.org/wiki> <https://trac.webkit.org/wiki 
>>>> <https://trac.webkit.org/wiki>> to whatever new documentation we create.  
>>>> Most information on that wiki is extremely outdated or outright wrong.
>>> 
>>> That very much depends on the section of Trac’s Wiki you’re looking at. 
>>> https://trac.webkit.org/wiki/TestExpectations 
>>> <https://trac.webkit.org/wiki/TestExpectations> is ancient, but pretty 
>>> accurate, for example. Same for 
>>> https://trac.webkit.org/wiki/LayoutTestsSearchPath 
>>> <https://trac.webkit.org/wiki/LayoutTestsSearchPath> (despite the 
>>> references to ancient MacOS versions). We need to do some serious clean up 
>>> (which probably involves a lot of deletion), but blind deletion seems 
>>> unwise.
>> 
>> Where did I suggest blind delete? My suggestion is to very selectively 
>> migrate information.
> 
> You did suggest that “we don’t migrate contents of 
> https://trac.webkit.org/wiki <https://trac.webkit.org/wiki>”. If we want to 
> selectively migrate information from Trac, we still need a place to migrate 
> that information to.

We don’t have to migrate all the information in trac wiki to one place. Some of 
them may belong to webkit.org <http://webkit.org/> website, while others are 
best added to ReadMe.md or Introduction.md. One of the reasons trac wiki is in 
such a disarray right now is because there isn’t a clear organization & a well 
defined audience. Migrating all the wiki entires to new place will not fix 
those problems. For that matter, what we really need to focus on here is sort 
out which information belongs to where instead of creating a yet another place 
to dump information to.

> Introduction.md is definitely not the right place for much of this, so that 
> leaves the GitHub Wiki (which, I might point out, was never discussed as a 
> community either, I started it so we could discuss migrating Trac in the 
> future, but it’s never been officially “blessed") or Brandon’s DocC 
> documentation repo as the two proposed choices

I don’t think those two are only solutions. Namely, I suggest we create a new 
documentation repository using a cross-platform tool written in Python, Ruby, 
or Perl such that contributors don’t need to learn yet another programming 
language or runtime thereof.

- R. Niwa

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

Reply via email to