I feel like that's actually pretty easy with Github actions? I think maybe there's even one that exists Github Pages and probably any other static site generator thingy we could care to name. Related, I stumbled across this the other day: https://github.com/apache/beam-site which appears to be unused which could probably even have different review and committer sets if we wanted?
On Thu, Sep 21, 2023 at 3:19 PM Robert Bradshaw via dev <dev@beam.apache.org> wrote: > 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 :-) >>>>>>>> >>>>>>>
