Hi Pulsarers, As we move forward with PIP 87 [1], we’ve migrated the Pulsar website contents to an independent repo, pulsar-site, per the agreement made by our community [2].
This migration makes us think of the doc repo. After thinking twice, our recommendation is to **keep the Pulsar doc repo as it is** in the pulsar repo [3] rather than migrate it to the pulsar-site repo [4]. Context: - Currently, Pulsar doc and code are hosted in the same GitHub repo, which causes some doc management issues (such as hard to measure the quality and usage of doc). - Examples of other open source communities that use separate GitHub repos for doc and code are Kubesphere, PingCAP, Milvus. To some degree, it enhances the efficiency of doc management and development workflow. - Separate doc repo has many advantages, however, after weighing up pros and cons of the two methods, we do not choose it. We’ve summarized below both methods to highlight the benefits and limitations. ACTION: Please review and vote within 72 hours. **If there is no discussion or objection, we’ll keep it as it is (method 1).** We’d love your feedback! Thanks! ~~~~~~~~~~~~~~~~~~ # Method 1 Pulsar doc and code are in the **same** GitHub repo. ## Advantages 1) Doc contributors do not need to change their habits. Pulsar doc contributors are accustomed to updating docs at the pulsar repo [3]. 2) Manage code PRs and their relevant doc PRs and issues conveniently. Contributors can get all the information about issues (eg. what’s the issue, issue resolution process, etc) and link them in one repo. ## Disadvantages 1) To some degree, it’s difficult to improve the efficiency of doc management and development workflow. If doc and code are hosted in the same GitHub repo, it is hard to collect and analyze doc metrics. ~~~~~~~~~~~~~~~~~~ # Method 2 Pulsar doc and code are in **different** GitHub repos. ## Advantages 1) Improve the efficiency of doc management and development workflow. If doc is hosted in an independent GitHub repo, it is easier to measure the quality and usage of our documentation. For example, we can collect metrics from GitHub Insights or other tools like SourceLevel [5], to understand dynamics and adjust appropriately. ### Disadvantages 1) Doc contributors need to change where they update documentation. CHANGE: Pulsar doc contributors need to update docs at the pulsar-site repo [4]. 2) Doc commits are calculated in the pulsar-site rather than the pulsar repo, which may decrease doc visibility. 3) Contributors need to manage code PRs and their relevant doc PRs and issues in two different repos. ~~~~~~~~~~~~~~~~~~ [1] https://lists.apache.org/thread/vrd764pv66mbnctttk2h3dvvhls92bgy [2] https://lists.apache.org/thread/06sl2mh5jm1llq12w5m4hw6pvfx32vkd [3] https://github.com/apache/pulsar [4] https://github.com/apache/pulsar-site [5] https://sourcelevel.io/
