devoncarew
commented
9 months ago I did look at some of the options here when this came up on discord a few days ago. I see the downsides of the (current) wiki being:
- non-repo committers can't send PRs to update the content
- repo comitters can't get their changes code reviewed (this is more desirable for some types of docs than for others)
They do have benefits in that they're discoverable and that they're easy for committers to update.
Some options for a replacement:
plain markdown files in an sdk directory
- markdown is easily editable
- they're as easy for people to contribute to as any other sdk file
- all changes get the benefit of code review; we could choose to abbreviate the process for some types of docs if useful
- easy to organize (in directories, ..) and they display well in github
markdown files in the sdk, rendering to html via jekyll
This would convert the markdown files to html as a github action and serve them via github pages. We'd control the styling here and changes to the files would also go through code review. Some drawbacks:
- more setup than the first option
- less apparent to readers that they could send changes to the content
- you have to do more of the site nav yourself - some initial work setting up the jekyll templates
markdown files in the repo, rendered to docusaurus
This is similar to the 2nd option but we'd render to docusaurus (see [docusaurus.io](https://docusaurus.io/ - a fairly polished documentation UI). Some drawbacks:
- very likely more polish than we need for repo getting started / contributing / maintenance docs
- more moving parts; the .md files are interpreted by the generation system as .mdx files, so we'd need to escape some chars and syntax
parlough
GitHub wiki's doesn't have a great workflow since only those with write access can edit it. There is also no review, which is admittedly less important since it is contributor facing docs, but contributor docs are important too and deserve to be thoughtfully considered and correct.
It's also separated from the rest of development, so updating them requires a separate step from landing a CL, and it's simply often forgotten. If you visit the SDK wiki now, there are some pages that don't make sense and others that are out of date.
To enable easier contribution and foster an environment where contribution docs are public, written, and maintained, we should consider moving them into the repository. These could be separated by team and/or project (like the VM docs now) and linked to from a central location or all centrally located, perhaps in the mostly untouched
/docsfolder or in a new/contributorsfolder.GitHub's inline markdown viewing is generally sufficient, even with an autogenerated TOC and header anchors, but if desired/needed the docs could always be hosted on GitHub pages or consumed by dart.dev.
This migration could be completed incrementally, giving a chance to discard now irrelevant pages and update others as necessary.
To reduce contribution friction I would encourage this directory (if centrally located) would be excluded from any extra OWNERS requirements.
As a personal aside, I raise that building on this foundation and creating a culture of public documentation of both SDK contribution processes and SDK implementation details/internals has many benefits. I constantly hear about how much Dart user's love @mraleph's Introduction to Dart VM and how they want more documents like it. If we ever want to see Dart for Education succeed, the SDK will need to be better understood and approachable, and this is would be a helpful step towards that. š