HI Aizhamal, Thank you for working on documentation improvement! This should be very helpful even if Beam site is in quite good shape now (though it lacks updates on new features and revision of the old ones).
> On 27 Jan 2020, at 08:33, Aizhamal Nurmamat kyzy <[email protected]> wrote: > > First, is to enable internationalization and localization of the Apache Beam > website to increase the reach of the project. We can do this by migrating the > current website from Jekyll do Docsy [2]. Docsy supports internationalization > out-of-the-box. Other projects have been very successful enabling platforms > that allow their users to contribute a translation of the documentation and > make the project accessible to non-english speakers. Examples are Kubernetes, > Tensorflow and Apache Airflow. Do we have any user demands for documentation translation into other languages? I’m asking this because, in my experience, it’s quite tough work to translate everything and it won’t be always up-to-date with the mainstream docs in English. Also, moving to another doc engine probably will require us to change a format of mark-up language or not?. What are the other advantages of Docsy over Jekyll? > Second, is to work on the content of the website to make the user onboarding > experience easier. This includes updating tutorials and quickstarts, > deprecating outdated or irrelevant sets of documentation, and creating new > documentation that is currently lacking. From the conversations with both new > and experienced users, it is clear that there are a number of new features > (Schemas, State and Timers, new Python IOs, etc) that are not documented. > Documentation for existing features can also be improved. We also plan to add > new pages with useful knowledge about Beam (its Ecosystem, past workshops, > talks and upcoming meetups) that will provide Beam users additional support > in their journey towards adoption. This should be an excellent improvemnet because many new features are suffering from not being very visible for users. I’d be happy to help with that. > > Third, rework the knowledge architecture to be more intuitive and improve > website functionality for better and faster user onboarding. Include relevant > links in the Apache Beam docs to additional contributor resources on Beam > Cwiki to make new contributor experience better. I’d also suggest to improve Beam site context search to be able to differentiate search queries over user documentation and/or API references.
