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 07:10:34 GMT
Yes, you are right, sorry. I did not think about this because I have been using it here
with my PhD students for free…

Cheers,
-heri

> On Dec 10, 2015, at 07:34, Till Westmann <tillw@apache.org> wrote:
> 
> I’d also like to keep it on ASF infrastructure, but I guess that’s not a hard requirement
for docs.
> 
> However, it seems that we’d need to pay for bitbucket for a team of more than five.
> Isn’t that right?
> 
> Thanks,
> Till
> 
> On 9 Dec 2015, at 22:25, Heri Ramampiaro wrote:
> 
>> 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