asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Maxon <ima...@uci.edu>
Subject Re: Internal documentation
Date Mon, 07 Dec 2015 22:38:04 GMT
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 <tillw@apache.org> 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 <chenli@gmail.com> 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 <chenli@gmail.com> 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 <tillw@apache.org> 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 <kisskys@gmail.com>
>>>
>>> wrote:
>>>>>>
>>>>>>
>>>>>>> It seems to provide a way for collaborator to work together by
>>>>>>> invitation.
>>>>>>>
>>>>>>> ---------- Forwarded message ----------
>>>>>>> From: Young-Seok Kim <kisskys@gmail.com>
>>>>>>> Date: Tue, Dec 1, 2015 at 8:39 PM
>>>>>>> Subject: Re: Internal documentation
>>>>>>> To: dev@asterixdb.incubator.apache.org
>>>>>>>
>>>>>>>
>>>>>>> Sorry, it's not editable. :(
>>>>>>>
>>>>>>> On Tue, Dec 1, 2015 at 8:38 PM, Young-Seok Kim <kisskys@gmail.com>
>>>
>>> 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 <tillw@apache.org>
>>>
>>> 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 <chenli@gmail.com>
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
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>
>>>
>

Mime
View raw message