The tight coupling between CLI and doc only exists because someone thought it was a good idea to make the build fail if the documentation isn't updated according to the output of some script.

However, we don't have this going on for the discovery CLI, and seems like Fabric survived just fine without the automatic coupling.

In the end, no automatic process can replace personal responsibility of code committers and maintainers that review the code.

To decouple the tight coupling between CLI build and documentation, we can have a github action that is triggered post merge and updates some kind of button like:

---

From: fabric@... <fabric@...> on behalf of David Enyeart <enyeart@...>
Sent: Wednesday, July 20, 2022 11:19 PM
To: Ry Jones <rjones@...>; fabric@... <fabric@...>
Cc: Community Architects <community-architects@...>
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Proposal to move Fabric docs into a distinct repo

 

I think we need to get one level deeper on a proposal… Any impact to ReadTheDocs? Can it transparently point to a different repo? How about the older release branches? How would maintainers be structured? An overall set of maintainers and then

ZjQcmQRYFpfptBannerStart

This Message Is From an External Sender

This message came from outside your organization.

 

ZjQcmQRYFpfptBannerEnd

I think we need to get one level deeper on a proposal…

 

Any impact to ReadTheDocs? Can it transparently point to a different repo? How about the older release branches?

 

How would maintainers be structured? An overall set of maintainers and then maintainers per language? Who would they be? Recall that the fabric-docs-i18n repo was created outside of Fabric because the core Fabric maintainers didn’t have bandwidth to oversee and maintain it.

 

How to handle the tight coupling of Fabric build and doc. E.g. generation of command reference doc from the Fabric command line utilities, generation of the metrics doc, and the current checks to ensure they don’t get out of sync each build:

https://github.com/hyperledger/fabric/blob/main/scripts/help_docs.sh

https://github.com/hyperledger/fabric/blob/main/scripts/metrics_doc.sh

 

Who would perform the decoupling work?

 

How exactly is the separate i18n doc repo painful? How exactly would this change alleviate the pain? Do we expect any issues introduced from the decoupling to be less painful than the current i18n pain?

 

 

From: fabric@... <fabric@...> on behalf of Ry Jones <rjones@...>
Date: Wednesday, July 20, 2022 at 3:23 PM
To: fabric@... <fabric@...>
Cc: Community Architects <community-architects@...>
Subject: [EXTERNAL] [Hyperledger Fabric] Proposal to move Fabric docs into a distinct repo

Hi, Currently, several Hyperledger projects keep documentation in repos outside of the main code repo; Besu being the most active. This allows documentation to have a distinct reviewer set, among other wins. I propose the creation of a fabric-docs

ZjQcmQRYFpfptBannerStart

This Message Is From an External Sender This message came from outside your organization.

ZjQcmQRYFpfptBannerEnd

Hi,

Currently, several Hyperledger projects keep documentation in repos outside of the main code repo; Besu being the most active. This allows documentation to have a distinct reviewer set, among other wins. I propose the creation of a fabric-docs repo which contains the current documentation with commit history; this will help i18n efforts, as well.

Ry

Ry Jones

Community Architect, Hyperledger

Book a meeting Chat on Discord

 

 

On Wed, Jul 20, 2022 at 12:06 PM David Enyeart <enyeart@...> wrote:

I would certainly consider that. What is the full proposal? What has worked well for other projects?  Could you start a new topic dedicated to the doc proposal?

I would certainly consider that. What is the full proposal? What has worked well for other projects?  Could you start a new topic dedicated to the doc proposal?