asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chen Li <che...@gmail.com>
Subject Re: Internal documentation
Date Tue, 08 Dec 2015 07:20:12 GMT
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 <tillw@apache.org> 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 <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