TL; DR, we should add the Markdown documents about the pulsar-site repo in GitHub. DON'T USE GOOGLEDOCS EVERYWHERE!
---- Currently Pulsar's website is maintained in https://github.com/apache/pulsar-site. However, I cannot find any document of this document repo. As a contributor, if I want to contribute to this repo, I will look at the README first: https://github.com/apache/pulsar-site/blob/main/README.md However, I can barely find what I concerns about in it: - Where should I add the content - What should I do before opening a PR (e.g. building a preview) - How can I build a preview in my local env - How will the web page be updated due to the changes of this repo If I were a frontend engineer, I might also want to know how to develop the website for it. What I can find is: [Preview Website Changes](https://docs.google.com/document/d/1wszdtMRo6MhKbVaggPK7_bnKaC4TewuT--GWZZxJNGg/edit#heading=h.wu6ygjne8e35) from https://github.com/apache/pulsar-site/tree/main/site2/website-next. Yeah, I believe nobody will click into this directory if he cannot find anything from the README.md in the root directory. BTW, the details are in the external GoogleDocs link in https://github.com/apache/pulsar#documentation-1 There is a terrible case recently: How to add the release note also changed after https://github.com/apache/pulsar-site/pull/227, we need to update them in JavaScript files. However, in https://github.com/apache/pulsar/blob/master/wiki/release/release-process.md#write-release-notes, there is no update in [Pulsar Release Notes Guide](https://docs.google.com/document/d/1cwNkBefKyV6OPbEXnUrcCdVZi0i2BezqL6vAL7VqVC0/edit#). If the release manager wants to know how to contribute the release notes, he might tend to find a previous PR like https://github.com/apache/pulsar-site/pull/209. Unfortunately, it's outdated. We have to update the `.js` files now, e.g. https://github.com/apache/pulsar-site/pull/242 IMO, we should add a guidance into the pulsar-site repo. In addition, the documents should be maintained in GitHub as much as possible. It's better not just pasting an external GoogleDocs link. We can use GoogleDocs for the temporary changes, but we should present a stable Markdown document in GitHub. Thanks, Yunze
