Personally I feel using markdown to do internal documentation is an overkill, since each change needs to go through the git process. So I prefer wiki. If Confluence wiki needs to be replaced, we should find a new wiki ASAP and start the practice.
Nevertheless, I am OK with the idea of using markdown to do the docs. Chen On Wed, Dec 9, 2015 at 5:06 PM, Till Westmann <[email protected]> wrote: > I generally agree with your preference, but Ted suggested that the > confluence wiki might not be here forever. And as > a) migrating content is painful (especially as we intend to produce > more of it) and > b) putting content into markdown format seems to be relatively > futureproof and > c) our website is built from markdown sources > it seems to me that putting it directly to the website might be a > better investment. > > Does this make sense? > > Cheers, > Till > > > On 7 Dec 2015, at 23:20, Chen Li wrote: > >> 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 >>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>> >>>>>>>>> >>>>>>> >>>>> >>> >
