openwhisk-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dominic Kim <style9...@gmail.com>
Subject Re: Write down some documents which describe OW internals
Date Thu, 18 Apr 2019 08:35:58 GMT
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 <mrutkows@us.ibm.com>님이 작성:

> 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 <style9595@gmail.com>
> 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
>
>
>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message