Re: Write down some documents which describe OW internals
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
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
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
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