Contribution Guide +1 Github WebUI +1 Pull requests +1 Rest: Inspect + Adapt
2017-03-13 19:38 GMT+01:00 Stefan Podkowinski <s...@apache.org>: > 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). > >> > >
