Official CS docs

[benjamin roth <br...@gmail.com>]

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

Re: Official CS docs

[benjamin roth <br...@gmail.com>]

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 <sp...@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
> >
>

Re: Official CS docs

[Stefan Podkowinski <sp...@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/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
>