asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Till Westmann" <ti...@apache.org>
Subject Re: Internal documentation
Date Thu, 10 Dec 2015 01:06:52 GMT
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