I think that this is a one way street. There’s a way to put markdown
into confluence, but I think that there is no (Atalassian-provided) way
to export the confluence content as markdown.
But I’ll be happy to be corrected on this one.
Cheers,
Till
On 9 Dec 2015, at 18:02, Ildar Absalyamov wrote:
I am confused, does’t Confluence allow markdown syntax?
https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html#ConfluenceWikiMarkup-markdown
<https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html#ConfluenceWikiMarkup-markdown>
In this case we can keep using Confluence, while it’s still there
and easily migrate documentation on the site, if that will be needed.
On Dec 9, 2015, at 17:55, Chen Li <[email protected]> wrote:
Personally I feel using markdown to do internal documentation is an
overkill, since each change needs to go through the git process. So
I
prefer wiki. If Confluence wiki needs to be replaced, we should find
a new wiki ASAP and start the practice.
Nevertheless, I am OK with the idea of using markdown to do the docs.
Chen
On Wed, Dec 9, 2015 at 5:06 PM, Till Westmann <[email protected]>
wrote:
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
Best regards,
Ildar
