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
