couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <bchesn...@gmail.com>
Subject Re: couchdb internals doc repo
Date Wed, 30 Oct 2013 08:53:45 GMT
On Wed, Oct 30, 2013 at 9:42 AM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:

> On Wed, Oct 30, 2013 at 9:34 AM, Benoit Chesneau <bchesneau@gmail.com>
> wrote:
> > Anyway I really think a good doc items should be organised first before
> > putting anything in a melting pot  and reorganise them after. What makes
> a
> > good doc is the ability of the user to find rapidly an information
> without
> > having to sort after.
>
> I don't disagree, my point is more about the process of getting there.
> I think it's much easier to gather up all the documentation that we
> have already and try to iterate on it to improve organization &
> coherency, rather than starting from scratch and wanting to write
> everything to be just perfect. It also provides a better interim
> solution -- in between starting to collect/write and getting to a
> state of having the perfect developer docs, it would be better to have
> a disorganized collection of docs in a place that's easy to find (and
> contribute to) than having some separate place containing half-written
> docs or an outline of what it will grow to be.
>
>
The mailing-list is here to help us to coordinate the work imo. Especially
since we have the possibility to always provide a fresh snapshot to our
users.

The way we could organise our work could be the following:

1) Start a topic where we define first parts of the dev doc and put in
front the docs we currently have
2) Create the parts in our doc with a WIP header (something like we have in
some wikipedia articles)
3) Port the items collected in (1) to the repo in parts created in (2)

and iterate again using the mailing list by proposing new docs. That will
help to collaborate on the doc imo. At least more than the current process
that happen most of the time in the dark rooms of irc. If some are OK with
such workflow I will start the new thread asap.

- benoit

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message