I read the document and left a few simple comments. I would like us to discuss about three things.
1. Architecture from the technical side. I'm not sure if it's about creating a Airflow's site or creating documentation for Airflow. For me, these are two independent things. Pytorch consist of multiple components: * Site: This is built using the Jekyll static page generator https://pytorch.org/get-started/locally/ https://pytorch.org/features https://pytorch.org/hub https://pytorch.org/blog/ Repo: https://github.com/pytorch/pytorch.github.io * Tutorial: This is sphinx-based docs https://pytorch.org/tutorials/ Repo: https://github.com/pytorch/tutorials * Documentation: This is sphinx-based docs https://pytorch.org/docs/1.0.0/ https://pytorch.org/docs/0.2.0/ Repo: https://github.com/pytorch/pytorch/tree/master/docs * Sphinx theme. It is used by documentation and tutorial. The site does not use this Repo: https://github.com/pytorch/pytorch_sphinx_theme There are still a few other components, but they do not matter. I would not want all things mixed together in the case of Airflow. If we agree that we want to have a similar architecture to Pytorch, then we need a static website ex. Jekyll and sphinx documentation. The current documentation should be updated to be based on a new theme. We also need a way to easily publish changes and documentation that will describe how to make popular changes on the site. For example: publication of documentation for a new version of the product. In such architecture, the contractor should provide the following elements: a) design files including icons. It should be accepted by the community on dev list. b) sphinx theme. It should be accepted by the community on Github as a PR. c) static website. It should be accepted by the community on Github as a PR. 2. Integration with CI/CD. The document "ReadTheDocs" is often used in the document. It is a service that allows publishing documentation based on a master branch. Unfortunately, it causes a lot of problems on our scale of source code. Currently ongoing and unresolved problem: https://apache-airflow.slack.com/archives/CJ1LVREHX/p1561724137011200 A big plus is easy configuration and automatic content publishing. Unfortunately, this is also a big restriction because we do not have much control over the building process. I think it's worth thinking about a different mechanism. I spoke about it on the Slack channel - #documentation, so I will copy my statement: > Can we add an additional step in CI that will send documentation to GCS or > other service? In the near future, we should have a some information about > the credits in GCP. GCS is very cheap, so cutting out of these credits should > not be a problem If we get credits then the configuration of sending > documentation for each branch/PR should not be problematic. This is just a > vision of the future of course. Building on RTD is becoming problematic and I > think it is worth rethinking it. > This is especially important if we realize that the documentation/the website > will be intensively developed in the future. > https://docs.google.com/document/d/15nFhFlC__nm2_kRqCCT4a6fYRLnnIf6ATjDqlQACdKo/edit# > I do not know who will take care of this task ( ;-) ), but I think that he > will have to take care of this problem. I did a similar task for another > project last week. The documentation is available for viewing for each > person and works more stable than ReadTheDocs. 3. Multilingual website Is the whole documentation to be in several languages? I think it will be very difficult to maintain the high quality of each version. I think that the website can be in all languages, but the documentation should be in English only. https://airflow.apachecn.org/#/ The Chinese-speaking community has created documentation in their language, but I'm afraid it is up to date. Greetings, Kamil Breguła On Mon, Jun 3, 2019 at 11:24 PM Aizhamal Nurmamat kyzy <[email protected]> wrote: > > Hello everyone, > > As some of you may remember, earlier this year I have suggested adding a > landing page for Apache Airflow[1], also introduced a prototype we could > use [2], but we may want to have something professionally done for Airflow > :) > > I have been working with the Google Cloud Composer team to allocate some > budget for revamping the Airflow website and it got approved, yay! > > I would like to discuss the requirements for the website with the community > as I am not an expert in this matter. I started this document[3] where you > can add your thoughts and comments. > > After we finalize the requirements, the vendors we will choose to work with > will: > - Design the website: the design approval will be done in the dev@ list by > the community > - Develop the website: testing and improvement suggestions will be done in > the dev@ list by the community > > While we think of the requirements, I especially want to emphasize the work > we need to do around restructuring the Documentation page for Airflow > (navigations, meaningful divisions into related topics/subtopics, etc). > Other pages like Blog, Community, etc are more straightforward in my > opinion. > > Let me know if you have any questions. > > Thanks, > Aizhamal > > > > [1] > https://lists.apache.org/thread.html/94e9f68ef8a3c42df0c1f78d3eff711c4761c1cf27fe2d3603ca961b@%3Cdev.airflow.apache.org%3E > [2] > https://lists.apache.org/thread.html/d12fa36f75e9a35cb70ba5d3a91003dac79fd92977c465c091e12b77@%3Cdev.airflow.apache.org%3E > [3] > https://docs.google.com/document/d/15nFhFlC__nm2_kRqCCT4a6fYRLnnIf6ATjDqlQACdKo/edit?usp=sharing
