Personally, I believe doc is a critical component to any software project, especially a project like Apache Geode, and so, is the project really “complete “(or should thee codebase really be frozen during a release) if the doc is not done or consistent yet?
Having the doc be part of the source allows the doc to be (theoretically) in-sync with the codebase as it evolves, as it should be. On the other hand, with a separate repo, it does allow corrections or other alterations to be made at the risk of growing inconsistency, which is a huge impediment IMO. In Asciidoc, doc can even be based on the source in part (e.g. interfaces). Ideally, I don’t see code and doc being separate or even fundamentally different. This sounds more like a process problem and a workaround to a broken process, to me. $0.02 -John From: Dave Barnes <dbar...@apache.org> Date: Tuesday, June 14, 2022 at 12:15 PM To: dev@geode.apache.org <dev@geode.apache.org> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo ⚠ External Email I'd like to move the doc sources for the Geode User Guide from the code repo (https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjblum%40vmware.com%7Cb6ae14ef841e416fb22208da4e3a2bb4%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308999514633%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vWegMzha9uIc8JMMAYhgxU20V9beAoSbAFOK5aORAfc%3D&reserved=0) to a separate geode-docs repo. The primary reason is to allow docs to cycle at their own rate, rather than in lock-step with the code. The present arrangement causes problems during releases, when code is frozen (including doc sources) to prepare a release candidate. This is exactly the time when critical last-minute doc changes are needed, but such changes are forbidden due to the code freeze. I have participated in the Geode project since its inception, and can confidently state that this conflict arises with nearly every Geode release. Setting up the docs in a separate repo would alleviate this regularly-recurring, counter-intuitive situation. Of note: The docs directories and toolset are almost entirely independent of directories and tools needed for code development and release, so removal of the doc sources from the Geode code repo should be painless for developers. Observations and opinions welcome... Dave Barnes ________________________________ ⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
