Thanks for the information! I think this approach works very well for purely technical docs like CQL documentation. For building a growing knowledge base I think the git repo is too developer-centric. A good example is that question about "fire drill" on the user list. There is someone who would like to contribute but probably not as a developer. So that process is a bit awkward for him. Imageine of an FAQ or troubleshooting section with 100s or 1000s of entries. Doing that in files will either end up with unmaintainable large files or large directories. In this case we aren't talking any more of "some docs" that describe things that are closely related to code but a database that helps people to answer questions and to solve problems. There are many topics on the user list that pop up every now and then. If there was a database that could hold many answers of already asked questions, that would be a great thing. There are a lot of resources out there that answer a lot of questions but they are hard to find and filter - especially for newbies. Having a central and official place for that kind of resources would just be awesome. And IMHO the hurdle to contribute should be as low as possible.
That said, I unfortunately don't have the perfect solution out of the box. I can understand why you chose .rst for the (technical) docs but what I have in mind goes beyond that. Generally I think of it more as a DB with taggable articles (since version, until version, related to, see also, ...) than a pure document structure. You could also do that in a WIKI but I'm not sure if this is the best solution. What solution could work also depends if a technical doc (kind of reference) and a knowledge base should stay in the same system or if they are separated. I think it is not uncommon to separate purely technical docs from "support sections". I will think about it - maybe others as well - and if I see a proper solution, I will bring it to the table. These kind of things can't be decided or solved within a few minutes, ideas have to grow first. 2017-03-01 13:11 GMT+01:00 Stefan Podkowinski <s...@apache.org>: > 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/029e1273675260630e4973ba301f71 > a8de5a9d7e294a7b2df6eed65f@%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 > > >
