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 :-) >>>>>> >>>>>
