asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Till Westmann" <ti...@apache.org>
Subject Re: Internal documentation
Date Thu, 10 Dec 2015 06:34:54 GMT
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