Replies in line to keep on the discussion of what we might want to put in different venues. But it does sound like there's enough support to at least get started on getting our wiki set up to be accessible.
For general context
I can't seem to edit even though it says anyone can. JB - are you still admin? I'd be happy to help.
The use of wiki vs. docs vs. the (repo-backed) website seems to be one of convenience vs. polish
Wiki vs. docs vs. web site is about other things, too:
- presentation style (slightly different from polish)
- target audience for each piece of content better (get started contributing vs deep dive tutorials)
- separating large-scale "worlds" of content (vs just different pages on the site) to avoid distractions (even polished design docs are a distraction for a user-facing site)
, and totally orthogonal to dev vs. user-facing stuff.
User-facing content requires way more polish! But it also has other important differences, like expectations, and the relative importance of concision vs. comprehensiveness.
I'm not opposed to a wiki, but personally I think a lot of our dev-facing docs (e.g. testing, ptransform style guide, portability overview) benefit from being in a more polished, permanent form (in particular, have been improved going through the code review process).
I do like having review for things that are meant to last. I don't have a technical solution in mind for that. I don't think they are mutually exclusive anyhow.
Very technical stuff like asf-site/README.md are IMHO best put right next to the sources/artifacts they describe.
Yea the site README is an example that isn't so bad. I do still get a lot of questions, because people don't know it is where they should look. The worse examples might be the main beam/README.md and sdk/CONTAINERS.md which are basically invisible. I think a big problem here is discoverability which is very poor for sprinkled docs. It could remain poor on the wiki if we make disjoint pages without good breadcrumb paths, but at least there's search.
On the flip side, no need to limit the wiki to contributor-focused material.
I disagree strongly here - I don't think the wiki will have appropriate polish for users. Even if carefully polished I don't think the presentation style is right, and it is not flexible. Power users will find it, of course.
+1 most of the contributor material could live on Wiki and there it will be easier to maintain (perhaps the lower bar for updates will lead to more information and increased maintenance). Contribution policy related material should remain on the website and go through proper review/versioning.