OK so this did turn into a discussion all about the tech/hosting :-). It has been 5 years and we have experience of the wiki now so maybe that is fair anyhow. And perhaps the preference of where to put information cannot be separated from it.
Top posting because there was so much in common across the responses and I agree mostly too so I'll merge & paraphrase. > Focusing the main website primarily toward users is good Seems everyone still agrees with this > The wiki is not reviewed and our docs we care about should be Agree. > Wiki syntax is an old thing that is not quite markdown and should just be markdown Agree. > Wiki is yet another place to go, hard to navigate, not discoverable. Agree. So the "neverending argument" is so far unanimous on this particular thread :-) --------------- My personal preferences are: - markdown - reviewed - organized... - ...independently of code folders - discoverable/orientable aka top/side nav So large markdown files don't meet "organized" and collections of READMEs don't meet "independently of code folders" and a docs/ folder in the repo doesn't meet "discoverable/orientable aka top/side nav". Seems like a new place is needed to meet all the desires. CONTRIBUTING.md is a good example to dissect. The integration with GitHub is great, but it should be super *concise* (so as not to discourage anyone) and have only information that *every* contributor should learn when they are *new*. Any information not meeting all those criteria needs a different home. I did a quick search to see if there was a standard answer to having top and side nav for a docs/ folder of markdown in your github repo. I guess that is GitHub Pages? TBH I have used them happily in the distant past but somehow I thought they had been deprecated or something. Kenn On Thu, Sep 21, 2023 at 1:18 PM Danny McCormick via dev <dev@beam.apache.org> wrote: > > I might be wrong but I think of wiki as a more volatile and a less > reliable place than the Website > > I agree, the counterpoint is that docs that require more work to update > are more likely to go stale since there is higher friction to update. > There's also more of an expectation that everything is polished, which may > or may not be desirable. > > In practice, the end result is that wiki guides are more comprehensive but > messier (and to your point a little less reliable and I'd add less > discoverable, though that's fixable). To me, that is an ok tradeoff to make > with developer guides. Also, note that the contribution guide itself is in > GitHub markdown - CONTRIBUTING.md > <https://github.com/apache/beam/blob/master/CONTRIBUTING.md> - to me > that's something we should definitely not change since that is the broadly > agreed upon standard for GitHub projects and gets special treatment from > GitHub. > > > ------------------------------------------------------------------------------------------------------------------------------------ > > Mostly, my vote is predicated on maintaining consistency with the decision > in https://lists.apache.org/thread/w4g8xpg4215nlq86hxbd6n3q7jfnylny and > wanting to avoid relitigating that decision (since code review vs no code > review on dev docs is a neverending argument that has played out many times > across many projects with no clear winner and it is tightly coupled with > personal preference). If the decision was "dev stuff" goes to confluence, > then the contribution section seems to be a clear place to draw the line > since that is all by definition "dev stuff". > > Thanks, > Danny > > On Thu, Sep 21, 2023 at 12:58 PM Chamikara Jayalath <chamik...@google.com> > wrote: > >> I might be wrong but I think of wiki as a more volatile and a less >> reliable place than the Website (can be updated without a review by any >> committer and we do that quite often). I think things in the >> contribution guide are key to a healthy Beam community so I'd like them to >> be in a more stable place that gets reviewed appropriately when updated. >> >> Thanks, >> Cham >> >> On Thu, Sep 21, 2023 at 9:14 AM Danny McCormick via dev < >> dev@beam.apache.org> wrote: >> >>> +1 on moving the release guide. I'd argue that everything under the >>> `contribute` tag other than the main page ( >>> https://beam.apache.org/contribute/) and the link to CONTRIBUTING.md >>> <https://github.com/apache/beam/blob/master/CONTRIBUTING.md> makes more >>> sense on the wiki (we can keep the section with the sidebar links just >>> redirecting to the wiki). I don't think it makes sense to move anything >>> else, but the contributing section is inherently "dev focused". >>> >>> Thanks, >>> Danny >>> >>> On Thu, Sep 21, 2023 at 11:58 AM Kenneth Knowles <k...@apache.org> >>> wrote: >>> >>>> Hello! >>>> >>>> I am reviving a discussion that began at >>>> https://lists.apache.org/thread/w4g8xpg4215nlq86hxbd6n3q7jfnylny when >>>> we started our Confluence wiki and has even been revived once before. >>>> >>>> The conclusion of that thread was basically "yes, let us separate the >>>> contributor-facing stuff to a different site". It also was the boot up of >>>> the Confluence wiki but I want to not discuss tech/hosting for this thread. >>>> I want to focus on the issue of having a separate user-facing website vs a >>>> contributor-facing website. Some things like issue priorities are >>>> user-and-dev facing and they require review for changes and should stay on >>>> the user site. I also don't want to get into those more complex cases. >>>> >>>> We are basically in a halfway state today because I didn't have enough >>>> volunteer time to finish everything and I did not wrangle enough help. >>>> >>>> So now I am release manager and encountering the docs more closely >>>> again. The release docs really blend stuff. >>>> >>>> - The main release guide is on the website. >>>> - Some steps, though, are GitHub Issues that we push along from >>>> release Milestone to the next one. >>>> - The actual technical bits to do the steps are sometimes on the >>>> confluence wiki >>>> - I expect I will also be touching README files in various folders of >>>> the repo >>>> >>>> So I just want to make some more steps, and I wanted to ask the >>>> community for their current thoughts. I think one big step could be to move >>>> the release guide itself to the dev site, which is currently the wiki. >>>> >>>> What do you think? Are there any other areas of the website that you >>>> think could just move to the wiki today? >>>> >>>> Kenn >>>> >>>> p.s. Some time in the past I saw an upper right corner fold (like >>>> https://www.istockphoto.com/illustrations/paper-corner-fold) that took >>>> you to the dev site that looked the same with different color scheme. That >>>> was fun :-) >>>> >>>
