> - reviewed Generally, I'm actually probably -0 on this one - it depends on context, but things that are for other developers only are usually better off without this requirement IMO since you get more contributions and more useful/unpolished things. Unfortunately, I'm not sure if confluence actually meets the bar for easy to update though because getting an account/initial setup is a pain. So I'm -0 since I don't know of a tool that both allows people to easily edit and avoids spam, but if such a tool exists I'd strongly prefer that.
> - discoverable/orientable aka top/side nav I'm -1 on this requirement. A structured in-repo `docs` folder and/or a dedicated developer documentation repo have worked well on teams I've been on in the past and it avoids having to maintain additional infrastructure for a website. It also brings folks closer to the code, making edits more likely. These look nice, but I don't know how much value they actually add. > 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. I'm probably -1 on pages because at that point we've got 2 different website setups, one using hugo (https://beam.apache.org/) and one using Jekyl (pages); at that point, we might as well just move things totally back into the website and just have it live under a separate section of the site. My vote if we're moving away from confluence (which seems fine) would be either a dedicated `docs` or `developer-docs` folder or a separate markdown only repo. On Thu, Sep 21, 2023 at 3:30 PM Kenneth Knowles <k...@apache.org> wrote: > 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 :-) >>>>> >>>>
