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 <[email protected]> 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 <[email protected]> wrote: >> >>> It seems to provide a way for collaborator to work together by >>> invitation. >>> >>> ---------- Forwarded message ---------- >>> From: Young-Seok Kim <[email protected]> >>> Date: Tue, Dec 1, 2015 at 8:39 PM >>> Subject: Re: Internal documentation >>> To: [email protected] >>> >>> >>> Sorry, it's not editable. :( >>> >>> On Tue, Dec 1, 2015 at 8:38 PM, Young-Seok Kim <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 >>>>> >>>>> >>>> >>>> >>> >
