The static content idea seems very doable to me. We could either put it in markdown as a separate part of asterix-doc (not as part of the user-level docs), or into the incubator.apache.org site. The former approach is nice because it would be part of the normal source itself. We already have a job on the apache CI server that runs mvn site in asterix-doc/ on each commit anyway.
Just my $0.02 though :) I'm curious to hear what other folks think about where to put the docs if Confluence isn't the right place. - Ian On Wed, Dec 2, 2015 at 6:12 PM, Till Westmann <[email protected]> wrote: > > On 2 Dec 2015, at 17:08, Ted Dunning wrote: > >> Confluence has been a real problem at Apache. It is likely to become >> deprecated. > > > Ok, it seemed to work pretty well so far. > What are the problems that people see with confluence? > >> 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. > > > How is that implemented? Where is the translation running and who > commits the static pages to the site repo? > > Thanks, > Till > > > >> >> 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 >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>> >>>>> >>> >
