asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ildar Absalyamov <ildar.absalya...@gmail.com>
Subject Re: Internal documentation
Date Thu, 10 Dec 2015 02:02:22 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message