Agreed. Let's not give up on this as quickly. My suggestion is to at least provide a getting started guide for writing docs, before complaining about too few contributions. I'll try to draft something up this week.
What people are probably not aware of is how easy it is to contribute docs through github. Just clone our repo, create a document and add your content. It's all possible through the github web UI including reStructuredText support for the viewer/editor. I'd even say to lower the barrier for contributing docs even further by accepting pull requests for them, so we can have a fully github based workflow for casual contributors. On 03/13/2017 05:55 PM, Jonathan Haddad wrote: > Ugh... Let's put a few facts out in the open before we start pushing to > move back to the wiki. > > First off, take a look at CASSANDRA-8700. There's plenty of reasoning for > why the docs are now located in tree. The TL;DR is: > > 1. Nobody used the wiki. Like, ever. A handful of edits per year. > 2. Docs in the wiki were out of sync w/ cassandra. Trying to outline the > difference in implementations w/ nuanced behavior was difficult / > impossible. With in-tree, you just check the docs that come w/ the version > you installed. And you get them locally. Huzzah! > 3. The in-tree docs are a million times better quality than the wiki *ever* > was. > > I urge you to try giving the in-tree docs a chance. It may not be the way > *you* want it but I have to point out that they're the best we've seen in > Cassandra world. Making them prettier won't help anything. > > I do agree that the process needs to be a bit smoother for people to add > stuff to the in tree side. For instance, maybe for every features that's > written we start creating a corresponding JIRA for the documentation. Not > every developer wants to write docs, and that's fair. The accompanying > JIRA would serve as a way for 2 or more people to collaborate on the > feature & the docs in tandem. It may also be beneficial to use the dev-ml > to say "hey, i'm working on feature X, anyone want to help me write the > docs for it? check out CASSANDRA-XYZ" > > Part of CASSANDRA-8700 was to shut down the wiki. I still advocate for > this. At the very minimum we should make it read only with a big notice > that points people to the in-tree docs. > > On Mon, Mar 13, 2017 at 8:49 AM Jeremy Hanna <jeremy.hanna1...@gmail.com> > wrote: > >> The moinmoin wiki was preferred but because of spam, images couldn’t be >> attached. The options were to use confluence or have a moderated list of >> individuals be approved to update the wiki. The decision was made to go >> with the latter because of the preference to stick with moinmoin rather >> than confluence. That’s my understanding of the history there. I don’t >> know if people would like to revisit using one or the other at this point, >> though it would take a bit of work to convert. >> >>> On Mar 13, 2017, at 9:42 AM, Nate McCall <zznat...@gmail.com> wrote: >>> >>>> Isn't there a way to split tech docs (aka reference) and more >>>> user-generated and use-case related/content oriented docs? And maybe to >> use >>>> a more modern WIKI software or scheme. The CS wiki looks like 1998. >>> The wiki is what ASF Infra provides by default. Agree that it is a bit >>> "old-school." >>> >>> I'll ask around about what other projects are doing (or folks who are >>> involved in other ASF projects, please chime in). >>
