I generally agree with your preference, but Ted suggested that the
confluence wiki might not be here forever. And as
a) migrating content is painful (especially as we intend to produce
more of it) and
b) putting content into markdown format seems to be relatively
futureproof and
c) our website is built from markdown sources
it seems to me that putting it directly to the website might be a
better investment.
Does this make sense?
Cheers,
Till
On 7 Dec 2015, at 23:20, Chen Li wrote:
My preference:
- External docs: Markdown as part of the source code (i.e., our
current practice);
- Internal docs: wiki (Confluence or something better).
On Mon, Dec 7, 2015 at 10:11 PM, Till Westmann <[email protected]>
wrote:
Yes, I agree that the static content of the site should be doable.
As we need to run Jekyll manually it’s a little more involved than
the wiki, but if the wiki is not a long term solution, then it’s
better to move sooner than later.
I think that it would make sense to split the asterix-doc
documentation into user documentation and developer documentation
and reuse the build infrastructure as you suggested.
Cheers,
Till
On 7 Dec 2015, at 14:38, Ian Maxon wrote:
The static content idea seems very doable to me. We could either put
it in markdown as a separate part of asterix-doc (not as part of the
user-level docs), or into the incubator.apache.org site. The former
approach is nice because it would be part of the normal source
itself.
We already have a job on the apache CI server that runs mvn site in
asterix-doc/ on each commit anyway.
Just my $0.02 though :) I'm curious to hear what other folks think
about where to put the docs if Confluence isn't the right place.
- Ian
On Wed, Dec 2, 2015 at 6:12 PM, Till Westmann <[email protected]>
wrote:
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
