> On Sep 29, 2022, at 11:48 AM, Jonathan Bedard via webkit-dev > <webkit-dev@lists.webkit.org> wrote: > > >>> On Sep 20, 2022, at 1:52 PM, Brent Fulgham <bfulg...@apple.com> wrote: >>> >>>> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev >>>> <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>> 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. > > 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. >>>>> 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. >>> >>> 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? >>> 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> 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. - R. Niwa
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org https://lists.webkit.org/mailman/listinfo/webkit-dev
