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
