asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Heri Ramampiaro <heri...@gmail.com>
Subject Re: Internal documentation
Date Thu, 10 Dec 2015 06:25:44 GMT
What about Bitbucket? 

To me Bitbucket seems to “fulfill” all suggested requirements: wiki support, markdown,
git integration etc.

Any thoughts?

Cheers
-heri


> On Dec 10, 2015, at 07:08, Till Westmann <tillw@apache.org> wrote:
> 
> 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 <chenli@gmail.com> 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 <tillw@apache.org> 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 <tillw@apache.org>
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 <tillw@apache.org>
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 <chenli@gmail.com>
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 <chenli@gmail.com>
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
<tillw@apache.org>
>>>>>>>>>>> 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 <kisskys@gmail.com>
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> wrote:
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>>> It seems to provide a way for collaborator
to work together by
>>>>>>>>>>>>>> invitation.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> ---------- Forwarded message ----------
>>>>>>>>>>>>>> From: Young-Seok Kim <kisskys@gmail.com>
>>>>>>>>>>>>>> Date: Tue, Dec 1, 2015 at 8:39 PM
>>>>>>>>>>>>>> Subject: Re: Internal documentation
>>>>>>>>>>>>>> To: dev@asterixdb.incubator.apache.org
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Sorry, it's not editable. :(
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> On Tue, Dec 1, 2015 at 8:38 PM, Young-Seok
Kim
>>>>>>>>>>>>>> <kisskys@gmail.com>
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 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 <tillw@apache.org>
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 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 <chenli@gmail.com> 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


Mime
View raw message