Hi Benjamin I think the best way to catch up with the motivation behind this is by reading the following dev post and linked jiras:
https://lists.apache.org/thread.html/029e1273675260630e4973ba301f71a8de5a9d7e294a7b2df6eed65f@%3Cdev.cassandra.apache.org%3E What are your suggestions to improve the documentation? I think it's fair to say that the official docs still leave a lot to be desired. But wikis or any other publishing tools each have their on strengths and drawbacks. Do you have any example project with a process that we should follow instead? Did you have a look at the README file in the docs tree and actually try to add or change any content? What would hold you back to work from there and submit a patch? On 01.03.2017 11:10, benjamin roth wrote: > Hi guys, > > Is there a reason that the docs are part of the git repo? > In my personal opinion this is very complicated and it puts the hurdle to > contribute to docs very high. > > There are so many questions on userlists that repeat over and over again > and that could be put into a knowledge base. > > But ... > - Maintaining this in a repo is a painful, complicated and slow. > - I don't like to write docs that I can't preview instantly. I don't want > to wait for a slow deployment process to see my result. > - There are tons of solutions for agile and moderated document management > like wikis or CMS. > - Doc access is not bound to contribution access and can be handled more > relaxed. > > One thing that supports my consideration is the fact that the official doc > site is sparse and contains a lot of TODOs or "Under construction" entries. > > IMHO Doc vs Source is like userlist vs devlist. > > Any thoughts? > > Cheers, > Ben >
