Re: Write down some documents which describe OW internals

2019-04-24 Thread Matt Sicker
I like the documentation approach as it allows for more
documentation-driven feature enhancements. Similar to what I've
suggested in the past about OpenWhisk Improvement Proposals. Also nice
for more casual contributors who would otherwise be too intimidated by
such a broad project.

On Thu, 18 Apr 2019 at 03:56, Bertrand Delacretaz
 wrote:
>
> Hi,
>
> On Thu, Apr 18, 2019 at 10:44 AM Dominic Kim  wrote:
> > ...Initially, I`ve naively thought of two options.
> > 1. Including docs in core repo.
> > 2. Including docs in cwiki or wiki in core repo. ...
>
> To me a third option is blog posts, which have the advantage that they
> don't need to be maintained: they express your current view, which
> might still be valuable later even if it gets out of sync when things
> evolve. OpenWhisk can get a blog at https://blogs.apache.org/ if
> desired, or a blog section might be created at
> http://openwhisk.apache.org/ for more informal content than what's
> there now.
>
> Apart from that, consolidating docs is great, of course - I just
> wanted to mention the difference between reference docs and
> informative articles which are also useful.
>
> -Bertrand



-- 
Matt Sicker 


Re: Write down some documents which describe OW internals

2019-04-18 Thread Bertrand Delacretaz
Hi,

On Thu, Apr 18, 2019 at 10:44 AM Dominic Kim  wrote:
> ...Initially, I`ve naively thought of two options.
> 1. Including docs in core repo.
> 2. Including docs in cwiki or wiki in core repo. ...

To me a third option is blog posts, which have the advantage that they
don't need to be maintained: they express your current view, which
might still be valuable later even if it gets out of sync when things
evolve. OpenWhisk can get a blog at https://blogs.apache.org/ if
desired, or a blog section might be created at
http://openwhisk.apache.org/ for more informal content than what's
there now.

Apart from that, consolidating docs is great, of course - I just
wanted to mention the difference between reference docs and
informative articles which are also useful.

-Bertrand


Re: Write down some documents which describe OW internals

2019-04-18 Thread Dominic Kim
Initially, I`ve naively thought of two options.
1. Including docs in core repo.
2. Including docs in cwiki or wiki in core repo.

With the first option, new people will be able to easily find the documents
and we can guarantee the freshness of the documents as it resides in core
repo.
(It will urge contributors to update the document as the architecture
changes over time.)

With the second option, we can write down the document in cwiki or wiki and
link it in the core repo.
The document can easily become stale as contributors can overlook it when
making a change on OW internals.

But as you mentioned, it would be better to host the documents on the
website.
Aside from it, I feel like documents in OpneWhisk is somewhat scattered.
We have some documents on the websites and some documents in core repo
written in markdown, some documents in cwiki or wiki in core repo.

I didn't look into it deeply, but it seems our website is maintained in the
different project and being rendered via Jekyll. (
https://github.com/apache/incubator-openwhisk-website)
I want to raise a discussion to consolidate them into one.

In Apache Kafka, it seems they are maintaining HTML files in the core repo
and hosting documents and their website via those files.
https://github.com/apache/kafka/tree/trunk/docs

I don't want to say we need to follow their rules, but it was easy for me
to look into their documents as all information is provided in one place.

In short, I want to suggest to consolidate all docs and serve them on the
websites.
It is optional, but if we include such docs in the core repo, it would be
useful to keep them updated.


I  want to listen to any opinion or feedbacks.

Best regards
Dominic



2019년 4월 18일 (목) 오전 4:08, Matt Rutkowski 님이 작성:

> That would be a very welcome addition to our docs. indeed.  Please let me
> know if you have any ideas about how we might expose (cross-ref.) the
> resultant info better via our website or confluence wiki would be happy to
> help there.
>
>
>
> From:   Dominic Kim 
> To: dev@openwhisk.apache.org
> Date:   04/16/2019 05:29 AM
> Subject:Write down some documents which describe OW internals
>
>
>
> Dear whiskers.
>
> When I started to involve in this project, I felt the learning curve of
> OpenWhisk is relatively steep.
> It has many components, flows, edge cases and the fundamental difficulties
> coming from Scala.
>
> So how about writing down some documents about OpenWhisk internals?
> I am thinking of writing down documents which explain basic architectures
> of each component, how activations flow the system, how entities are
> managed, and so on.
> There is a possibility that the documents could be stale in the future as
> the system is quickly changing, however, it would be a good starting point
> to help more people get involved in the project.
>
>
> Best regards
> Dominic
>
>
>
>
>


Re: Write down some documents which describe OW internals

2019-04-17 Thread Matt Rutkowski
That would be a very welcome addition to our docs. indeed.  Please let me 
know if you have any ideas about how we might expose (cross-ref.) the 
resultant info better via our website or confluence wiki would be happy to 
help there.



From:   Dominic Kim 
To: dev@openwhisk.apache.org
Date:   04/16/2019 05:29 AM
Subject:Write down some documents which describe OW internals



Dear whiskers.

When I started to involve in this project, I felt the learning curve of
OpenWhisk is relatively steep.
It has many components, flows, edge cases and the fundamental difficulties
coming from Scala.

So how about writing down some documents about OpenWhisk internals?
I am thinking of writing down documents which explain basic architectures
of each component, how activations flow the system, how entities are
managed, and so on.
There is a possibility that the documents could be stale in the future as
the system is quickly changing, however, it would be a good starting point
to help more people get involved in the project.


Best regards
Dominic