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:08:41 GMT
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