We've definitely used the website for more than that. We use it to document things for users, help developers know how to contribute, store drafts of designs, share user stories via blogs, do release announcements, and more. There's definitely space on the website to do this kind of thing, if we want to. We've used it that way before. If you only see it as a place "for user consumption after everything has been finalized", then you're missing out on the other ways we currently use the site, and the ways we've used it in the past.
With the website, most of the collaboration would happen in the GH issues about proposed designs or changes to designs, just like we do today with code or other documentation, which everybody is used to. I agree it's not as good as Google Docs for on-the-fly comments/annotations, but I don't think Confluence or Wiki are as good as that either, and Google Docs isn't really an option... unless you just want to link to it in the mailing list and stick to Google Docs from your personal Google account, until it's ready for publication, which would also be fine (any interested persons can simply request write access by replying to the message where you shared the link).. We are a much smaller project than many others, and we have previously suffered from having stuff too spread out. Even if other projects find a separate space valuable for them, I'm not sure it's best for the Accumulo project. While I think it's useful to examine what other projects do, I do think we should be careful to adopt anything just because others find it convenient for them. Confluence is my second choice, but with a big gap between it and my first choice. On a personal note: I hate using Confluence, because I think the navigation is highly unintuitive, as is the permissions model, and I don't like the idea of learning yet another wiki-syntax (though I've read Confluence supports some limited Markdown, but probably not the same as GitHub/Jekyll). I also do not want to set up custom notifications for watching yet another space. If we use Confluence, I will probably contribute very infrequently there because of my frustrations with having used it before. However, that would be my choice, and should not be a reason the project chooses one over another. I'm sharing my personal opinion only because it is influencing my opinion about the website being more accessible, via our current GitHub PR/issue/Markdown workflows, and I wonder how many other potential contributors would feel similarly. It's hard to know, since it seems like a lot of this is subjective, and is going to come down to a consensus of personal preferences. On Thu, Mar 2, 2023 at 3:46 PM Dave Marion <dmario...@gmail.com> wrote: > > I don't see the website as an area where we would have collaborative > discussions about an idea. For example, making comments and suggestions on > a document like you can do in Google Docs. I see the website as a place > where items are documented for user consumption after everything has been > finalized. I'm not trying to create a private discussion area, I think > anyone can see the wiki (but I think anonymous comments are disabled due to > spam issues). I see no issue with putting work-in-progress documents on a > wiki and referencing them via emails to the dev list. I think this is done > in a lot of other projects. Non-committers that don't have access to the > wiki and want to make comments, suggestions, and ask questions can do so > via the mailing list. I think it's also possible that people can get > confluence accounts (see https://issues.apache.org/jira/browse/INFRA-7058), > so if a non-committer wanted to participate they could. > > On Thu, Mar 2, 2023 at 2:53 PM Christopher <ctubb...@apache.org> wrote: > > > On Thu, Mar 2, 2023 at 1:34 PM Dave Marion <dmario...@gmail.com> wrote: > > > > > > I'm opposed to using the website for the reasons I specified earlier, so > > it > > > > Your reasons that I saw were: > > > > > 1. I don't think internal design discussions should go on the project > > website. > > > > That doesn't look to me like a reason. That appears to just be stating > > the conclusion. Did I miss your reason here? > > > > > 2. Changes to the design documents could not be seen by others right > > away (IIRC changes to the website are built and available at > > https://accumulo.staged.apache.org/, but human intervention is required > > to publish it at https://accumulo.apache.org/). > > > > What do you mean by "others" here? Do you mean "users", as opposed to > > "developers/contributors"? The ASF draws a distinction between > > "developers/contributors" and "users" as it pertains to official > > releases. Releases are intended to be consumed by users, and > > pre-release stuff is intended to be collaborative, open to all > > potential developers/contributors. Very very rarely are things > > reserved exclusively for committers. We don't even have a private > > committers space (the private mailing list is PMC-private, not > > committer-private). Having a distinction between users and developers > > doesn't mean we can't publish things on the website... it just means > > that we should be careful about how we do it, which is the same care > > we should take regardless of where we put it. Specifically, the care > > we need to take is to avoid marketing pre-release content to users. > > One way we can exercise this care for content on our website is that > > we can avoid sharing these unpolished designs by simply not linking > > them on the site, or by placing them in an area that is clearly marked > > as intended for devs. But, we have no similar distinction between > > committers and non-committer devs for which we should avoid sharing > > pre-release content under development. In fact, it is the opposite... > > we should be developing openly so as to allow room for non-committers > > to become committers through participation in development activities. > > > > As for the staging/publication of the website, that's just a mechanic > > for verifying the website isn't broken before we serve it. It's not a > > mechanism for keeping things internal vs. shared and doesn't have > > anything to do with the separation between devs and users. We already > > publish Draft contents to the website, as well as developer-specific > > documentation not intended for users. > > > > We've even specifically published work-in-progress design documents > > there, of the same type that seems to be the basis of this > > conversation (https://accumulo.apache.org/design/system-snapshot). I > > would strongly prefer us to continue to do it this way, rather than > > create a new space, and have these kinds of things scattered in > > multiple places. > > > > If, on the other hand, you intend to say that these should be private > > because they aren't ready for other potential contributors, then I > > would argue that we're an openly developed project... if something > > isn't ready to be shared with other potential contributors / > > developers, such that you want to keep it internal to existing > > committers, then it's not ready to be contributed to the project at > > all... because we don't restrict collaboration to only existing > > committers. That would prevent others from participating and earning > > the merit to become committers, and that's not something we should be > > doing. Anything that is okay to share with existing committers should > > be okay to share to other potential contributors who want to > > participate, and should be done in a space that allows them to do > > that. The website is a perfect space for that, and has everything we > > need. I'm actually not sure about Confluence... I suspect > > non-committers wouldn't be able to participate there because they > > probably can't get accounts for it. > > > > > > > looks like we need to > > > wait for INFRA to fix Confluence. I'd be curious how much we need to use > > > the mailing list during > > > the design phase. We can announce meeting dates/times on the mailing list > > > and post links to > > > meeting notes in Confluence. Ultimately, decisions made by the people > > that > > > want to be involved > > > will turn into pull requests against the codebase which comitters can > > weigh > > > in on. When you say, > > > "... but decisions about those would still need to be done on the mailing > > > list." Are you saying that > > > we need to discuss every single design decision on the mailing list? > > > > Yes and no. I am saying that decisions need to happen on the mailing > > list, but I agree with you that this can be satisfied through pull > > requests. I just wanted to emphasize that regardless of where we do > > that pre-decision collaboration, that collaboration should not be > > misconstrued as a decision to accept those ideas into the project. The > > decision occurs during the PR or other activity that interfaces with > > the mailing list, subsequent to the collaboration in the design/idea > > phase. > > > > As for the pre-decision collaboration space we're discussing, I just > > want to be careful that we're not creating such a space in an > > exclusionary way that allows only existing committers to participate, > > that excludes other potential contributors. This is still an > > openly-developed project, and we should collaborate in a space that is > > not exclusive to existing committers, but open to non-committer > > contributors and potential contributors as well. So, while we may want > > to keep a line separating dev activity from user consumption (an > > important separation that relates to official ASF releases), we should > > not be drawing a line between committer-devs as "internal" and > > contributor-devs as "external". The website, with its own issue > > tracker, the ability to render markdown, do reviews, and > > collaboratively edit, seems like the ideal place to me. We've used it > > before for the same purpose, and I think we should continue to do so. > > > > > > > > > > On Thu, Mar 2, 2023 at 12:56 PM Christopher <ctubb...@apache.org> wrote: > > > > > > > So, I agree a space would be helpful. Although it's old school and > > > > inconvenient, the mailing list is the canonical place for discussion. > > > > We currently use GitHub issues a lot, but that's copied to a mailing > > > > list (as is our old JIRA space), so if people want to participate > > > > without a GitHub account, they can still do that. There are certain > > > > options that are perhaps less convenient, such as just using the > > > > mailing list and our dev SVN space, but still more appropriate than > > > > options that would be less ubiquitous for potential participants. > > > > > > > > I think the ASF Confluence is probably fine, for storing, editing, and > > > > collaborating on shared documents, but decisions about those would > > > > still need to be done on the mailing list. If I remember correctly, we > > > > used to have a Wiki space, prior to it being transferred to > > > > Confluence, but it was poorly maintained, so we abandoned it in favor > > > > of using the website for docs. I could be mis-remembering, but I think > > > > this is the case. It might explain why you can't create a Confluence > > > > space. > > > > > > > > My preference would be to just use the website. I think it's fine to > > > > have a dev / design area of the website, and we can discuss on GitHub > > > > issues for the accumulo-website repo. That is a bit less convenient > > > > than Confluence if it's used heavily, but it's more convenient in the > > > > sense that it's more accessible and fits more in line with our current > > > > mode of operation. Plus, when a document is final, it's easy to link > > > > to from our documentation, without making users jump to another > > > > service to view docs. > > > > > > > > I would be opposed to using GitHub wiki or a new git repo. We have > > > > enough repos. Although it seems like they are free, there is still a > > > > lot of boilerplate work to maintain them, from managing > > > > .github/workflows, .github/CONTRIBUTING.md, etc., to .asf.yaml, to > > > > README, to keeping copyright dates updated in the NOTICE file, and > > > > more. > > > > > > > > In summary, my preference: > > > > > > > > 1. Keep a space in accumulo-website, discuss on GH issues and mailing > > > > list (strongly preferred) > > > > 2. Confluence, discuss on mailing list (prefer over other options, but > > > > not a fan) > > > > 3. GitHub wiki, discuss on mailing list (strongly prefer not to use > > this > > > > option) > > > > 4. New GitHub repo, discuss on GH issues and mailing list (strongly > > > > prefer not to use this option) > > > > > > > > On Thu, Mar 2, 2023 at 12:30 PM Ed Coleman <edcole...@apache.org> > > wrote: > > > > > > > > > > Currently, asf cannot create new wiki's because of a Confluence > > issue ( > > > > https://issues.apache.org/jira/browse/INFRA-24291) I chatted with > > infra > > > > and in response they created that issue. > > > > > > > > > > To expand on this discussion, I would like to toss out another > > > > alternative to discuss / explore. What if we used a separate GitHub > > > > project, something like Accumulo-Design, just like accumulo-proxy and > > > > accumulo-examples. As a separate project, it would be available for > > > > collaboration for the community, but remain separate from main project > > and > > > > the website to keep current code / documentation / design clearly > > separate > > > > from speculative design discussions. As a project: > > > > > > > > > > - document history would be preserved with git commit history. > > > > > - document collaboration could be done with normal PR submissions / > > > > reviews. > > > > > - issues could be used to discuss design aspects, capturing the > > comment > > > > history. > > > > > > > > > > The biggest downside is that it would be yet another project to > > follow / > > > > track. > > > > > > > > > > For me, I think the issue is that we need a public, collaborative > > space > > > > to hold design discussions. Neither the main project or the web-site > > seem > > > > quite appropriate and Confluence seems to lack the collaboration that > > can > > > > be achieved with github. > > > > > > > > > > We need a space to capture the redesign and whatever we select can be > > > > made to work - I'm just wondering what provides the easiest forum to > > build > > > > a collaborative space for the Accumulo community. > > > > > > > > > > Ed Coleman > > > > > > > > > > > > > > > On 2023/02/28 16:35:31 dlmar...@comcast.net wrote: > > > > > > Circling back on this issue - I agree that comments and such make > > > > sense for internal design documents. I'm going to create an INFRA > > ticket > > > > for a cwiki space for Accumulo unless there are any objections. > > > > > > > > > > > > -----Original Message----- > > > > > > From: Drew Farris <d...@ill.org> > > > > > > Sent: Saturday, February 25, 2023 5:16 PM > > > > > > To: dev@accumulo.apache.org > > > > > > Subject: Re: [DISCUSS] Enable Github wiki in asf.yaml? > > > > > > > > > > > > As mentioned, wikis can provide a streamlined collaborative editing > > > > workflow that's less labor intensive than updating a website. They can > > > > promote collaboration by providing specific tooling to support > > comments, > > > > revisions and iteration. > > > > > > > > > > > > In terms of preservation, GH wikis act just like any other Git > > > > repository, with a remote at (for example) g...@github.com: > > > > apache/accumulo.wiki.git > > > > > > IIRC the pages are just GH flavored markdown. There are at least a > > few > > > > Apache projects using them. > > > > > > > > > > > > However, GH wikis lack some features that I feel are important to > > > > support collaborative authoring. For example, the ability to comment > > and > > > > discuss specific passages in a document is a feature that's present in > > > > Cwiki, but not in GH wikis. I've come appreciate this this in my google > > > > docs and office workflows, so expect that it would be useful for > > Accumulo > > > > design discussions too. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > On Sat, Feb 25, 2023 at 2:54 PM Keith Turner <ktur...@apache.org> > > > > wrote: > > > > > > > > > > > > > I would like to try a wiki for design documents, I think it > > would be > > > > > > > less cumbersome than the website and we can always link from the > > > > > > > website and issues to the wiki. I think its ok to give it a try > > and > > > > > > > abandon it in the future, if abandoned would just need to > > properly > > > > > > > communicate that. The content should be archived in Apache > > > > > > > infrastructure, so if GH wiki does not do that then we should > > not use > > > > > > > it. If GH wiki is not an option then could try cwiki. > > > > > > > > > > > > > > On Sat, Feb 25, 2023 at 7:55 AM <dlmar...@comcast.net> wrote: > > > > > > > > > > > > > > > > I reverted the change. I didn't think it would be a big deal, > > but > > > > if > > > > > > > > it > > > > > > > requires discussion, then let's discuss it. > > > > > > > > > > > > > > > > I'm looking for a place to host information related to internal > > > > > > > > design > > > > > > > discussions. I envision these to be living documents that will be > > > > > > > updated over time as the design/implementation progresses and > > that > > > > > > > other committers will be able to comment on and edit. I don't > > feel > > > > > > > that the website is the correct place for this because: > > > > > > > > > > > > > > > > 1. I don't think internal design discussions should go on the > > > > > > > > project > > > > > > > website. > > > > > > > > 2. Changes to the design documents could not be seen by > > others > > > > > > > > right > > > > > > > away (IIRC changes to the website are built and available at > > > > > > > https://accumulo.staged.apache.org/, but human intervention is > > > > > > > required to publish it at https://accumulo.apache.org/). > > > > > > > > > > > > > > > > I looked in the INFRA issues and other projects are using the > > GH > > > > > > > > Wiki > > > > > > > feature and I saw no mention of backing it up or the requirement > > to > > > > do > > > > > > > so (maybe they rely on GitHub backing it up?). It does appear > > that we > > > > > > > would need an INFRA ticket so that they can modify the GitHub > > project > > > > > > > settings to lock the GitHub wiki down so that only committers can > > > > > > > modify it. If GitHub Wiki is not acceptable, then I think Apache > > > > > > > Confluence ( > > > > > > > https://cwiki.apache.org) might be an acceptable alternative. > > > > > > > > > > > > > > > > -----Original Message----- > > > > > > > > From: Christopher <ctubb...@apache.org> > > > > > > > > Sent: Saturday, February 25, 2023 4:41 AM > > > > > > > > To: accumulo-dev <dev@accumulo.apache.org> > > > > > > > > Cc: comm...@accumulo.apache.org > > > > > > > > Subject: Re: [accumulo] branch main updated: Enable Github > > wiki in > > > > > > > asf.yaml > > > > > > > > > > > > > > > > I don't recall a discussion about this change, but I think it > > goes > > > > > > > against previous efforts to make the website the one canonical > > > > > > > location for our documentation. I don't even think infra is > > backing > > > > up > > > > > > > wiki repos, so there wouldn't even be a record of the wiki > > contents > > > > in > > > > > > > ASF spaces (vs. the main repo, which is backed up to GitBox and > > the > > > > > > > issue tracker, which CCs the notifications list). > > > > > > > > > > > > > > > > In short, I think this should be reverted and we should not > > use the > > > > > > > GitHub wiki. If we need to store documents in a version > > controlled > > > > > > > way, we can store them on the website, or in our project's SVN > > dev > > > > > > > space. The wiki is just another place people would have to > > follow if > > > > > > > they want to participate, and I don't think that serves us. > > > > Therefore, > > > > > > > I think we shouldn't use it. > > > > > > > > > > > > > > > > > > > > > > > > On Fri, Feb 24, 2023, 15:59 <dlmar...@apache.org> wrote: > > > > > > > > > > > > > > > > > This is an automated email from the ASF dual-hosted git > > > > repository. > > > > > > > > > > > > > > > > > > dlmarion pushed a commit to branch main in repository > > > > > > > > > https://gitbox.apache.org/repos/asf/accumulo.git > > > > > > > > > > > > > > > > > > > > > > > > > > > The following commit(s) were added to refs/heads/main by this > > > > push: > > > > > > > > > new ae8a817e7b Enable Github wiki in asf.yaml > > ae8a817e7b is > > > > > > > > > described below > > > > > > > > > > > > > > > > > > commit ae8a817e7b2af8c64096ed1a4274eaef44c0e677 > > > > > > > > > Author: Dave Marion <dlmar...@apache.org> > > > > > > > > > AuthorDate: Fri Feb 24 15:59:10 2023 -0500 > > > > > > > > > > > > > > > > > > Enable Github wiki in asf.yaml > > > > > > > > > --- > > > > > > > > > .asf.yaml | 2 +- > > > > > > > > > 1 file changed, 1 insertion(+), 1 deletion(-) > > > > > > > > > > > > > > > > > > diff --git a/.asf.yaml b/.asf.yaml index > > bc2c943e82..08aa357082 > > > > > > > > > 100644 > > > > > > > > > --- a/.asf.yaml > > > > > > > > > +++ b/.asf.yaml > > > > > > > > > @@ -27,7 +27,7 @@ github: > > > > > > > > > - big-data > > > > > > > > > - hacktoberfest > > > > > > > > > features: > > > > > > > > > - wiki: false > > > > > > > > > + wiki: true > > > > > > > > > issues: true > > > > > > > > > projects: true > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
