My preference: - External docs: Markdown as part of the source code (i.e., our current practice); - Internal docs: wiki (Confluence or something better).
On Mon, Dec 7, 2015 at 10:11 PM, Till Westmann <[email protected]> wrote: > Yes, I agree that the static content of the site should be doable. > As we need to run Jekyll manually it’s a little more involved than > the wiki, but if the wiki is not a long term solution, then it’s > better to move sooner than later. > I think that it would make sense to split the asterix-doc > documentation into user documentation and developer documentation > and reuse the build infrastructure as you suggested. > > Cheers, > Till > > > On 7 Dec 2015, at 14:38, Ian Maxon wrote: > >> 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 >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>> >>>>>>> >>>>> >>> >
