Confluence has been a real problem at Apache. It is likely to become deprecated.
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. On Thu, Dec 3, 2015 at 12:03 PM, Chen Li <[email protected]> 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 <[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 > >>>>>> > >>>>>> > >>>>> > >>>>> > >>>> > >> >
