Yes, you are right, sorry. I did not think about this because I have been using it here with my PhD students for free…
Cheers, -heri > On Dec 10, 2015, at 07:34, Till Westmann <[email protected]> wrote: > > I’d also like to keep it on ASF infrastructure, but I guess that’s not a hard > requirement for docs. > > However, it seems that we’d need to pay for bitbucket for a team of more than > five. > Isn’t that right? > > Thanks, > Till > > On 9 Dec 2015, at 22:25, Heri Ramampiaro wrote: > >> What about Bitbucket? >> >> To me Bitbucket seems to “fulfill” all suggested requirements: wiki support, >> markdown, git integration etc. >> >> Any thoughts? >> >> Cheers >> -heri >> >> >>> On Dec 10, 2015, at 07:08, Till Westmann <[email protected]> wrote: >>> >>> I think that this is a one way street. There’s 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’ll be happy to be corrected on this one. >>> >>> Cheers, >>> Till >>> >>> On 9 Dec 2015, at 18:02, Ildar Absalyamov wrote: >>> >>>> I am confused, does’t Confluence allow markdown syntax? >>>> https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html#ConfluenceWikiMarkup-markdown >>>> >>>> <https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html#ConfluenceWikiMarkup-markdown> >>>> In this case we can keep using Confluence, while it’s still there and >>>> easily migrate documentation on the site, if that will be needed. >>>> >>>>> On Dec 9, 2015, at 17:55, Chen Li <[email protected]> wrote: >>>>> >>>>> 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 >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>> >>>>>>>> >>>>>> >>>> >>>> Best regards, >>>> Ildar
