We can certainly review the documentation on the Wiki. However, I think
that the review on the Wiki would happen after the document is written
as there seems to be no non-painful way to review these docs before they
are stored in the Wiki. (I also think that CTR (Commit-Then-Review) is
the right approach for docs.).
Wrt. the author and reviewer, I think that the creator of the page is
usually the author - so that’d be tracked by the Wiki and that we
would create tasks in JIRA to review certain documents? Does that make
sense?
All of this obviously assumes, that we’ll use the Wiki for this. I
think that I would prefer that as that’s a resource that’s part of
our project and on ASF infrastructure (even though the gitbook output
looks a lot nicer …).
My 2c,
Till
On 1 Dec 2015, at 22:33, Chen Li wrote:
@Young-Seok: it may be good if you can show a demo some time.
@Till: By "formal internal documentation" I mean pages with
high-quality
descriptions that have been reviewed. Each page needs to have an
author/owner with a reviewer.
https://cwiki.apache.org/confluence/display/ASTERIXDB/Design+Docs is a
good
starting point.
Chen
On Tue, Dec 1, 2015 at 8:55 PM, Young-Seok Kim <[email protected]>
wrote:
It seems to provide a way for collaborator to work together by
invitation.
---------- Forwarded message ----------
From: Young-Seok Kim <[email protected]>
Date: Tue, Dec 1, 2015 at 8:39 PM
Subject: Re: Internal documentation
To: [email protected]
Sorry, it's not editable. :(
On Tue, Dec 1, 2015 at 8:38 PM, Young-Seok Kim <[email protected]>
wrote:
I spent 45 minutes to create the following book for the demo
purpose:
https://www.gitbook.com/book/kisskys/asterixdb-internal-development-document/details
If you follow the link, you can
1. read the book online
2. download the book in pdf format
3. edit the book as well.
Please have a look.
Best,
Young-Seok
On Tue, Dec 1, 2015 at 6:00 PM, Till Westmann <[email protected]>
wrote:
A few people have already started to add design docs to our wiki
[1].
I think that that's not a bad place for such documents.
However, I'm not sure what "formal internal documentation" is.
The documents we have there so far are no necessarily formal - but
very
(!) helpful.
Cheers,
Till
[1]
https://cwiki.apache.org/confluence/display/ASTERIXDB/Design+Docs
On Dec 1, 2015, at 4:29 PM, Chen Li <[email protected]> wrote:
Per our recent discussions, we need to improve our protocol (if
any)
to do internal documentation so that knowledge can be archived and
accumulated. There are many possibilities.
One way I used in the past is: (1) Use wiki for formal internal
documentation; (2) Use Google Docs for interactive discussions,
but
final results should be converted into wiki pages. (3) Each wiki
page
has an author and a reviewer.
Other thoughts?
Chen
