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 Thu, 10 Dec 2015 01:55:41 GMT
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 <tillw@apache.org> 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 <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