You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Bastian Krol <ba...@tu-dortmund.de> on 2016/01/24 12:26:17 UTC
Documentation for CI
Hi folks,
I'd like to put up some documentation around the CI efforts somewhere.
Would the Confluence wiki be a good place for this? Or would you like to
see this somewhere else?
If Confluence is the right spot, it would be nice if one of you could
grant me write access (user name bastiankrol).
Suggestions where to put this in the page hierarchy in Confluence are
also welcome - most of the sections seem to be more targeted at users,
not so much at developers?
Cheers
Bastian
Re: Documentation for CI
Posted by Alexander Shorin <kx...@gmail.com>.
On Mon, Jan 25, 2016 at 6:53 PM, Jan Lehnardt <ja...@apache.org> wrote:
>> Why did you think that idea to keep CI documentation in the couchdb-ci
>> repository is bad?
>>
>> - couchdb-documentation is the place for project documentation. CI
>> could be described there from the point how to setup own build system.
>> That has a sense for me.
>
> I’d like to see our docs expanded to not just describing CouchDB the
> software, but the whole project, including how everything works, how
> CouchDB works internally, the whole shebang. Kinda like FreeBSD has
> everything in top-level books, just that we don’t need to split this
> up yet, and can get away with different sections of the same “document”.
All my 4 paws are up for this. Previous conception was different.
--
,,,^..^,,,
Re: Documentation for CI
Posted by Jan Lehnardt <ja...@apache.org>.
> On 25 Jan 2016, at 16:21, Alexander Shorin <kx...@gmail.com> wrote:
>
> On Mon, Jan 25, 2016 at 5:11 PM, Bastian Krol
> <ba...@tu-dortmund.de> wrote:
>>>> you can also just send them as PR to
>>>> https://github.com/apache/couchdb-documentation
>>>
>>> +1 for the docs for permanent documentation.
>>
>>
>> Thanks for the replies. I'll send a PR to couchdb-documentation for
>> permanent docs then at some time.
>>
>> However, I'll also would like to put a page somewhere to write down more
>> volatile content, like, what already has been done, what still needs to be
>> done, what is planned for the future, etc. I don't think that
>> couchdb-documentation is a good place for this.
>>
>> For this new-wiki seems to be the best place, right? If so, I'd still need
>> write access. Alternatively I can put it in the readme of the CI repository.
The wiki is totally fine for volatile things.
> Why did you think that idea to keep CI documentation in the couchdb-ci
> repository is bad?
>
> - couchdb-documentation is the place for project documentation. CI
> could be described there from the point how to setup own build system.
> That has a sense for me.
I’d like to see our docs expanded to not just describing CouchDB the
software, but the whole project, including how everything works, how
CouchDB works internally, the whole shebang. Kinda like FreeBSD has
everything in top-level books, just that we don’t need to split this
up yet, and can get away with different sections of the same “document”.
> - cwiki is the place for community driven documentation. Things,
> wisdom, knowledge and ideas provided by the whole our great community
> that relates to CouchDB project. Having CI docs there is...ok, but not
> sure that it's a good place.
>
> Why I think couchdb-ci repo is the good one?
>
> Because you git clone .../couchdb-ci.git, opens
> README.(md|rst|org|whatever) and see how the thing you cloned works.
> Any changes in the CI code would be easily to reflect in the README
> with the same commit, you your docs are strictly bounded to the code
> and that stuff is always in sync. And that's the one and the only
> place that everyone knows to go to read about CI stuff. So this makes
> things: simple, synced, predictable.
The repo should definitely include a bare minimum of project description,
but I wouldn’t mind seeing this on docs.couchdb.org as well.
Bastian, if it is easier, start out on couchdb-ci and then we can move it
to docs.c.o later.
Best
Jan
--
>
> Sounds good?
>
> --
> ,,,^..^,,,
Re: Documentation for CI
Posted by Alexander Shorin <kx...@gmail.com>.
On Mon, Jan 25, 2016 at 5:11 PM, Bastian Krol
<ba...@tu-dortmund.de> wrote:
>>> you can also just send them as PR to
>>> https://github.com/apache/couchdb-documentation
>>
>> +1 for the docs for permanent documentation.
>
>
> Thanks for the replies. I'll send a PR to couchdb-documentation for
> permanent docs then at some time.
>
> However, I'll also would like to put a page somewhere to write down more
> volatile content, like, what already has been done, what still needs to be
> done, what is planned for the future, etc. I don't think that
> couchdb-documentation is a good place for this.
>
> For this new-wiki seems to be the best place, right? If so, I'd still need
> write access. Alternatively I can put it in the readme of the CI repository.
Why did you think that idea to keep CI documentation in the couchdb-ci
repository is bad?
- couchdb-documentation is the place for project documentation. CI
could be described there from the point how to setup own build system.
That has a sense for me.
- cwiki is the place for community driven documentation. Things,
wisdom, knowledge and ideas provided by the whole our great community
that relates to CouchDB project. Having CI docs there is...ok, but not
sure that it's a good place.
Why I think couchdb-ci repo is the good one?
Because you git clone .../couchdb-ci.git, opens
README.(md|rst|org|whatever) and see how the thing you cloned works.
Any changes in the CI code would be easily to reflect in the README
with the same commit, you your docs are strictly bounded to the code
and that stuff is always in sync. And that's the one and the only
place that everyone knows to go to read about CI stuff. So this makes
things: simple, synced, predictable.
Sounds good?
--
,,,^..^,,,
Re: Documentation for CI
Posted by Bastian Krol <ba...@tu-dortmund.de>.
>> you can also just send them as PR to
>> https://github.com/apache/couchdb-documentation
> +1 for the docs for permanent documentation.
Thanks for the replies. I'll send a PR to couchdb-documentation for
permanent docs then at some time.
However, I'll also would like to put a page somewhere to write down more
volatile content, like, what already has been done, what still needs to
be done, what is planned for the future, etc. I don't think that
couchdb-documentation is a good place for this.
For this new-wiki seems to be the best place, right? If so, I'd still
need write access. Alternatively I can put it in the readme of the CI
repository.
Kind regards
Bastian
Re: Documentation for CI
Posted by Jan Lehnardt <ja...@apache.org>.
> On 24 Jan 2016, at 22:38, Robert Kowalski <ro...@kowalski.gd> wrote:
>
> Hi Bastian,
>
> you can also just send them as PR to
> https://github.com/apache/couchdb-documentation
+1 for the docs for permanent documentation.
I think we should reduce wiki usage to a minimum, and where it makes
most sense (like collaboratively collecting info).
Best
Jan
--
>
> I would prefer the official docs as single point of truth in the
> long-term, right now we have at least 4 sources (official docs,
> repository readmes, old-wiki, new-wiki) as possible sources and many
> sources are outdated. It's even worse: some are updated, some not,
> which makes it hard to decide which are still relevant and which not.
>
> On Sun, Jan 24, 2016 at 12:26 PM, Bastian Krol
> <ba...@tu-dortmund.de> wrote:
>> Hi folks,
>>
>> I'd like to put up some documentation around the CI efforts somewhere. Would
>> the Confluence wiki be a good place for this? Or would you like to see this
>> somewhere else?
>>
>> If Confluence is the right spot, it would be nice if one of you could grant
>> me write access (user name bastiankrol).
>>
>> Suggestions where to put this in the page hierarchy in Confluence are also
>> welcome - most of the sections seem to be more targeted at users, not so
>> much at developers?
>>
>> Cheers
>>
>> Bastian
Re: Documentation for CI
Posted by Andy Wenk <an...@apache.org>.
FULL ACK Robert! What brings us again to the point, that we should ask the
community to help consolidate all the various documentations. Like moving
from the old to the new wiki ...
On 24 January 2016 at 22:38, Robert Kowalski <ro...@kowalski.gd> wrote:
> Hi Bastian,
>
> you can also just send them as PR to
> https://github.com/apache/couchdb-documentation
>
> I would prefer the official docs as single point of truth in the
> long-term, right now we have at least 4 sources (official docs,
> repository readmes, old-wiki, new-wiki) as possible sources and many
> sources are outdated. It's even worse: some are updated, some not,
> which makes it hard to decide which are still relevant and which not.
>
> On Sun, Jan 24, 2016 at 12:26 PM, Bastian Krol
> <ba...@tu-dortmund.de> wrote:
> > Hi folks,
> >
> > I'd like to put up some documentation around the CI efforts somewhere.
> Would
> > the Confluence wiki be a good place for this? Or would you like to see
> this
> > somewhere else?
> >
> > If Confluence is the right spot, it would be nice if one of you could
> grant
> > me write access (user name bastiankrol).
> >
> > Suggestions where to put this in the page hierarchy in Confluence are
> also
> > welcome - most of the sections seem to be more targeted at users, not so
> > much at developers?
> >
> > Cheers
> >
> > Bastian
>
--
Andy Wenk
Hamburg - Germany
RockIt!
GPG fingerprint: C044 8322 9E12 1483 4FEC 9452 B65D 6BE3 9ED3 9588
https://people.apache.org/keys/committer/andywenk.asc
Re: Documentation for CI
Posted by Robert Kowalski <ro...@kowalski.gd>.
Hi Bastian,
you can also just send them as PR to
https://github.com/apache/couchdb-documentation
I would prefer the official docs as single point of truth in the
long-term, right now we have at least 4 sources (official docs,
repository readmes, old-wiki, new-wiki) as possible sources and many
sources are outdated. It's even worse: some are updated, some not,
which makes it hard to decide which are still relevant and which not.
On Sun, Jan 24, 2016 at 12:26 PM, Bastian Krol
<ba...@tu-dortmund.de> wrote:
> Hi folks,
>
> I'd like to put up some documentation around the CI efforts somewhere. Would
> the Confluence wiki be a good place for this? Or would you like to see this
> somewhere else?
>
> If Confluence is the right spot, it would be nice if one of you could grant
> me write access (user name bastiankrol).
>
> Suggestions where to put this in the page hierarchy in Confluence are also
> welcome - most of the sections seem to be more targeted at users, not so
> much at developers?
>
> Cheers
>
> Bastian