TBH, I'm not a huge fan of the wikis either. My ideal flow would be something like g3doc, and markdown files in github do a reasonable enough job emulating that. (I don't think the overhead of having to do a PR for small edits like typos is oneros, as those are super easy reviews to do as well...) For anything in-depth, a pointer to an "actual" doc with better collaborative editing tools is generally in order anyway.
I do feel strongly that https://beam.apache.org/contribute/ should remain on the main site, as it's aimed at users (who hopefully want to step up and contribute). The top level should probably mostly be a pointer to this, but I think it's valuable (for the audience that reaches it from github) to be a bit taylored to that audience (e.g. assume they just forked/downloaded the repository and want to edit-build-push. Generally a more advanced user than would find the page on the website.) The release guide? Meh. Wherever those doing releases find it most convenient. If that was me I'd probably put a markdown file right in the release directory next to the relevant scripts... (If not jump to literate programming right there :). On Thu, Sep 21, 2023 at 1:20 PM Kenneth Knowles <k...@apache.org> wrote: > > > On Thu, Sep 21, 2023 at 3:55 PM Danny McCormick <dannymccorm...@google.com> > wrote: > >> > - 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. >> > > I could go for this. I'm pretty -1 on a soup of files without any > information architecture or scattered throughout random folders. But I'm > probably -2 on the confluence wiki if such a thing is possible and it would > also remove a piece from our infra, so... I think I'd call it an upgrade to > have a folder full of docs. If we then make taxonomic subfolders that hide > all the information I'll be sad again. > > Ideally the developer-docs/ folder could be read as text, lightly rendered > like GH does, or fully rendered with navs. Yes, I am describing g3doc > (which is talked about publicly so I can name it, but I don't know what > the publicly-available equivalent is). None of the > website-building not-human-readable stuff from jekyll and hugo. > > Kenn > > >> >> 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 :-) >>>>>>> >>>>>>
