Return-Path: X-Original-To: apmail-asterixdb-dev-archive@minotaur.apache.org Delivered-To: apmail-asterixdb-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 607DD182AC for ; Thu, 10 Dec 2015 06:26:02 +0000 (UTC) Received: (qmail 89940 invoked by uid 500); 10 Dec 2015 06:26:02 -0000 Delivered-To: apmail-asterixdb-dev-archive@asterixdb.apache.org Received: (qmail 89887 invoked by uid 500); 10 Dec 2015 06:26:02 -0000 Mailing-List: contact dev-help@asterixdb.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@asterixdb.incubator.apache.org Delivered-To: mailing list dev@asterixdb.incubator.apache.org Received: (qmail 89874 invoked by uid 99); 10 Dec 2015 06:26:01 -0000 Received: from Unknown (HELO spamd4-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 10 Dec 2015 06:26:01 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd4-us-west.apache.org (ASF Mail Server at spamd4-us-west.apache.org) with ESMTP id 8009BC0295 for ; Thu, 10 Dec 2015 06:26:01 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd4-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -0.119 X-Spam-Level: X-Spam-Status: No, score=-0.119 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, URIBL_BLOCKED=0.001] autolearn=disabled Authentication-Results: spamd4-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com Received: from mx1-eu-west.apache.org ([10.40.0.8]) by localhost (spamd4-us-west.apache.org [10.40.0.11]) (amavisd-new, port 10024) with ESMTP id hkqw9Pnkw_MM for ; Thu, 10 Dec 2015 06:25:48 +0000 (UTC) Received: from mail-lf0-f41.google.com (mail-lf0-f41.google.com [209.85.215.41]) by mx1-eu-west.apache.org (ASF Mail Server at mx1-eu-west.apache.org) with ESMTPS id 15B1C24C66 for ; Thu, 10 Dec 2015 06:25:48 +0000 (UTC) Received: by lfdl133 with SMTP id l133so49620610lfd.2 for ; Wed, 09 Dec 2015 22:25:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=content-type:mime-version:subject:from:in-reply-to:date :content-transfer-encoding:message-id:references:to; bh=PX+titI+14nf+sJdw9lJZPI5BhUfE/YgN3pn08N33dc=; b=AWFWkJE6t4Oz/r1+J24jc3VaTS1XLwaZqTjLmcs3CAwlrjBU4HjKiUIosD7iY6Edy/ sqx7LvyhV0tFcwVxTKMoZ2cw3eekAoxHQU+6thDnHQFauRYhXTNdfONWgvJQqxIDEdm4 KeRyKly9pwA/wpqe30u56cOurmLr5RDfhMfCdsM+uIyHtTZrOGk0QaDiWJ53/04+bjXq 3E2k1Xfkv7vmYXL9m/e9AZVCALLMcIqXiaD1NNqO7ZYYELsxuAJ4s4ggwn72lMALo8ZT 0j3fzfhJ7l9uGuuYvClx/Ie+2X89QX5qBbOgOCdqm1Zj8eUoUt/r8wCbNt9FtWq9ZrT0 ORYA== X-Received: by 10.25.41.18 with SMTP id p18mr4569323lfp.75.1449728747382; Wed, 09 Dec 2015 22:25:47 -0800 (PST) Received: from dhcp-10-20-57-23.wlan.ntnu.no (129-241-231-192-gw.cgn.ntnu.no. [129.241.231.192]) by smtp.gmail.com with ESMTPSA id nq2sm1996767lbb.33.2015.12.09.22.25.45 for (version=TLS1 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 09 Dec 2015 22:25:45 -0800 (PST) Content-Type: text/plain; charset=utf-8 Mime-Version: 1.0 (Mac OS X Mail 9.1 \(3096.5\)) Subject: Re: Internal documentation From: Heri Ramampiaro In-Reply-To: Date: Thu, 10 Dec 2015 07:25:44 +0100 Content-Transfer-Encoding: quoted-printable Message-Id: <2F3B1ED1-94C2-4435-A3B7-AE241C7385F7@gmail.com> References: <827B4E68-FC49-4391-A762-9A86DF0D741E@apache.org> <59AB286B-AEA9-41B5-B023-2B9EAE8D17C7@apache.org> <82248A8F-5479-40BE-9406-8292F917B012@apache.org> To: dev@asterixdb.incubator.apache.org X-Mailer: Apple Mail (2.3096.5) What about Bitbucket?=20 To me Bitbucket seems to =E2=80=9Cfulfill=E2=80=9D all suggested = requirements: wiki support, markdown, git integration etc. Any thoughts? Cheers -heri > On Dec 10, 2015, at 07:08, Till Westmann wrote: >=20 > I think that this is a one way street. There=E2=80=99s a way to put = markdown into confluence, but I think that there is no = (Atalassian-provided) way to export the confluence content as markdown. > But I=E2=80=99ll be happy to be corrected on this one. >=20 > Cheers, > Till >=20 > On 9 Dec 2015, at 18:02, Ildar Absalyamov wrote: >=20 >> I am confused, does=E2=80=99t Confluence allow markdown syntax? = https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html= #ConfluenceWikiMarkup-markdown = >> In this case we can keep using Confluence, while it=E2=80=99s still = there and easily migrate documentation on the site, if that will be = needed. >>=20 >>> On Dec 9, 2015, at 17:55, Chen Li wrote: >>>=20 >>> 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. >>>=20 >>> Nevertheless, I am OK with the idea of using markdown to do the = docs. >>>=20 >>> Chen >>>=20 >>> On Wed, Dec 9, 2015 at 5:06 PM, Till Westmann = 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. >>>>=20 >>>> Does this make sense? >>>>=20 >>>> Cheers, >>>> Till >>>>=20 >>>>=20 >>>> On 7 Dec 2015, at 23:20, Chen Li wrote: >>>>=20 >>>>> My preference: >>>>>=20 >>>>> - External docs: Markdown as part of the source code (i.e., our >>>>> current practice); >>>>> - Internal docs: wiki (Confluence or something better). >>>>>=20 >>>>>=20 >>>>>=20 >>>>> On Mon, Dec 7, 2015 at 10:11 PM, Till Westmann = wrote: >>>>>>=20 >>>>>> Yes, I agree that the static content of the site should be = doable. >>>>>> As we need to run Jekyll manually it=E2=80=99s a little more = involved than >>>>>> the wiki, but if the wiki is not a long term solution, then = it=E2=80=99s >>>>>> 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. >>>>>>=20 >>>>>> Cheers, >>>>>> Till >>>>>>=20 >>>>>>=20 >>>>>> On 7 Dec 2015, at 14:38, Ian Maxon wrote: >>>>>>=20 >>>>>>> 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. >>>>>>>=20 >>>>>>> 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. >>>>>>>=20 >>>>>>> - Ian >>>>>>>=20 >>>>>>> On Wed, Dec 2, 2015 at 6:12 PM, Till Westmann = wrote: >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>> On 2 Dec 2015, at 17:08, Ted Dunning wrote: >>>>>>>>=20 >>>>>>>>> Confluence has been a real problem at Apache. It is likely to = become >>>>>>>>> deprecated. >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>> Ok, it seemed to work pretty well so far. >>>>>>>> What are the problems that people see with confluence? >>>>>>>>=20 >>>>>>>>> Thus, if you use it, you are likely to have to convert off to >>>>>>>>> something >>>>>>>>> else in the future. >>>>>>>>>=20 >>>>>>>>> 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. >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>> How is that implemented? Where is the translation running and = who >>>>>>>> commits the static pages to the site repo? >>>>>>>>=20 >>>>>>>> Thanks, >>>>>>>> Till >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>=20 >>>>>>>>>=20 >>>>>>>>> On Thu, Dec 3, 2015 at 12:03 PM, Chen Li = wrote: >>>>>>>>>=20 >>>>>>>>>> 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. >>>>>>>>>>=20 >>>>>>>>>> Comments? >>>>>>>>>>=20 >>>>>>>>>> Chen >>>>>>>>>>=20 >>>>>>>>>> On Wed, Dec 2, 2015 at 9:56 AM, Chen Li = wrote: >>>>>>>>>>>=20 >>>>>>>>>>>=20 >>>>>>>>>>>=20 >>>>>>>>>>> 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. >>>>>>>>>>>=20 >>>>>>>>>>> We will discuss with Young-Seok about gitbook to finalize = the tool. >>>>>>>>>>>=20 >>>>>>>>>>> Chen >>>>>>>>>>>=20 >>>>>>>>>>> On Tue, Dec 1, 2015 at 11:47 PM, Till Westmann = >>>>>>>>>>> wrote: >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> We can certainly review the documentation on the Wiki. = However, I >>>>>>>>>>>> think >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> that >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> the review on the Wiki would happen after the document is = written >>>>>>>>>>>> as >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> there >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> seems to be no non-painful way to review these docs before = they are >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> stored >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> in the Wiki. (I also think that CTR (Commit-Then-Review) is = the >>>>>>>>>>>> right >>>>>>>>>>>> approach for docs.). >>>>>>>>>>>>=20 >>>>>>>>>>>> Wrt. the author and reviewer, I think that the creator of = the page >>>>>>>>>>>> is >>>>>>>>>>>> usually the author - so that=E2=80=99d be tracked by the = Wiki and that we >>>>>>>>>>>> would >>>>>>>>>>>> create tasks in JIRA to review certain documents? Does that = make >>>>>>>>>>>> sense? >>>>>>>>>>>>=20 >>>>>>>>>>>> All of this obviously assumes, that we=E2=80=99ll use the = Wiki for this. I >>>>>>>>>>>> think >>>>>>>>>>>> that I would prefer that as that=E2=80=99s a resource = that=E2=80=99s part of our >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> project and >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> on ASF infrastructure (even though the gitbook output looks = a lot >>>>>>>>>>>> nicer >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> =E2=80=A6). >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> My 2c, >>>>>>>>>>>> Till >>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>>> On 1 Dec 2015, at 22:33, Chen Li wrote: >>>>>>>>>>>>=20 >>>>>>>>>>>>> @Young-Seok: it may be good if you can show a demo some = time. >>>>>>>>>>>>>=20 >>>>>>>>>>>>> @Till: By "formal internal documentation" I mean pages = with >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> high-quality >>>>>>>>>>>>>=20 >>>>>>>>>>>>>=20 >>>>>>>>>>>>>=20 >>>>>>>>>>>>> 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. >>>>>>>>>>>>>=20 >>>>>>>>>>>>> Chen >>>>>>>>>>>>>=20 >>>>>>>>>>>>> On Tue, Dec 1, 2015 at 8:55 PM, Young-Seok Kim = >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> wrote: >>>>>>>>>>>>>=20 >>>>>>>>>>>>>=20 >>>>>>>>>>>>>=20 >>>>>>>>>>>>>=20 >>>>>>>>>>>>>> It seems to provide a way for collaborator to work = together by >>>>>>>>>>>>>> invitation. >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>> ---------- Forwarded message ---------- >>>>>>>>>>>>>> From: Young-Seok Kim >>>>>>>>>>>>>> Date: Tue, Dec 1, 2015 at 8:39 PM >>>>>>>>>>>>>> Subject: Re: Internal documentation >>>>>>>>>>>>>> To: dev@asterixdb.incubator.apache.org >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>> Sorry, it's not editable. :( >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>> On Tue, Dec 1, 2015 at 8:38 PM, Young-Seok Kim >>>>>>>>>>>>>> >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> wrote: >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> I spent 45 minutes to create the following book for the = demo >>>>>>>>>>>>>>> purpose: >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> = https://www.gitbook.com/book/kisskys/asterixdb-internal-development-docume= nt/details >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> If you follow the link, you can >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> 1. read the book online >>>>>>>>>>>>>>> 2. download the book in pdf format >>>>>>>>>>>>>>> 3. edit the book as well. >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> Please have a look. >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> Best, >>>>>>>>>>>>>>> Young-Seok >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>> On Tue, Dec 1, 2015 at 6:00 PM, Till Westmann = >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> wrote: >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>> A few people have already started to add design docs to = our >>>>>>>>>>>>>>>> wiki >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> [1]. >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>> 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 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> very >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>> (!) helpful. >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>> Cheers, >>>>>>>>>>>>>>>> Till >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>> [1] >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> = https://cwiki.apache.org/confluence/display/ASTERIXDB/Design+Docs >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> On Dec 1, 2015, at 4:29 PM, Chen Li = wrote: >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> Per our recent discussions, we need to improve our = protocol >>>>>>>>>>>>>>>>> (if >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> any) >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> to do internal documentation so that knowledge can be = archived >>>>>>>>>>>>>>>>> and >>>>>>>>>>>>>>>>> accumulated. There are many possibilities. >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> 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 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>>> page >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> has an author and a reviewer. >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> Other thoughts? >>>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>> Chen >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>>=20 >>>>>>>>>>>>>>=20 >>>>>>>>>>>>=20 >>>>>>>>>>=20 >>>>>>>>=20 >>>>>>=20 >>>>=20 >>=20 >> Best regards, >> Ildar