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 <mrutk...@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 <style9...@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 > > > > >
