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 <[email protected]> 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 <[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 >>>>>> >>>>>> >>>>> >>>>> >>>> >>
