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 Wed, 02 Dec 2015 17:56:37 GMT
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