asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chen Li <che...@gmail.com>
Subject Re: Internal documentation
Date Thu, 03 Dec 2015 01:03:46 GMT
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
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>

Mime
View raw message