On 2 Dec 2015, at 17:08, Ted Dunning wrote:
Confluence has been a real problem at Apache. It is likely to become
deprecated.
Ok, it seemed to work pretty well so far.
What are the problems that people see with confluence?
Thus, if you use it, you are likely to have to convert off to
something
else in the future.
Drill and related projects like Calcite have had very good luck just
checking mark-down into git and either rendering the site on the fly
or
translating everything to static pages on commit.
How is that implemented? Where is the translation running and who
commits the static pages to the site repo?
Thanks,
Till
On Thu, Dec 3, 2015 at 12:03 PM, Chen Li <[email protected]> wrote:
Young-Seok showed me a demo of gitbook. Seems it has basic features
similar to Confluence Wiki. Gitbook doesn't have advanced features
available in Google Docs, such as commenting and real-time shared
editing. Thus I prefer to stay with the current Confluence Wiki.
People are welcome to use other tools such as Google Docs to share
work-in-progress docs, but the final info should go to Confluence
Wiki.
Comments?
Chen
On Wed, Dec 2, 2015 at 9:56 AM, Chen Li <[email protected]> wrote:
I agree with the "CTR (Commit-Then-Review)" approach for docs. My
main point was that a documentation needs to be read by another
person
other than the creator/author for obvious reasons.
We will discuss with Young-Seok about gitbook to finalize the tool.
Chen
On Tue, Dec 1, 2015 at 11:47 PM, Till Westmann <[email protected]>
wrote:
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
