V0.0.5

[TomKimsey]

This repo is intended to be used as a common documentation source for Ewon projects. It can be used as a git submodule to allow for easy updating of common documentation accross all projects.

[alexjhawk]

While I think the issue of duplicated common docs is a problem we need to solve, I am very unsure about using Git submodules as the solution.

Git submodules are powerful, but add extra steps to build the documentation. This adds more potential/room for confusion in the development environment, where developers should be building the documentation regularly (to accompany changelog modifications).

• There are developers outside of the solution center that contribute to documentation and/or have forks of projects.

Additionally, requiring additional steps harms the value of the starter project being the single point for common code/structure/files.

The common docs situation does need to be resolved, and I think there may be a few alternative solutions that are more native and/or don't require additional steps.

1. Use a Docusaurus plugin to import remote content from the relevant URL. Of interest is rdilweb/docusaurus-plugin-remote-content, which allows for remote content import without extra manual steps, but also includes support for adding/modifying/replacing content in the imported files in a customizable manner.
   • This could be added to the starter project and all repositories, referencing this repository, or it could be implemented to use the starter project as the 'content root' and cut out this repository. Either method works/is fine.
2. Create an npm module based out of this repository which would bundle the common documentation as a dependency that can be included in the starter project's yarn config, and in turn, the child repositories.
3. Use extensions library resources to bundle common docs files for use within connector/starter project child repositories. I'm not sure how the Docusaurus system would access the resources, but this is worth investigating as an alternative to requiring extra steps.

[TomKimsey]

Git submodules are powerful, but add extra steps to build the documentation. This adds more potential/room for confusion in the development environment, where developers should be building the documentation regularly (to accompany changelog modifications).

My view is that using git submodules is normal and a developer should be comfortable with using the tool. The minimal extra steps are not an issue to me.

Additionally, requiring additional steps harms the value of the starter project being the single point for common code/structure/files.

The intent would be for this to be included in the starter project as well.

The common docs situation does need to be resolved, and I think there may be a few alternative solutions that are more native and/or don't require additional steps.

How soon can a alternative be ready to use? What is the development effort required?
This solution is ready now and connector maintenance needs to be sustainable. We can always migrate to a more optimal solution in the future.

[alexjhawk]

Git submodules are powerful, but add extra steps to build the documentation. This adds more potential/room for confusion in the development environment, where developers should be building the documentation regularly (to accompany changelog modifications).

My view is that using git submodules is normal and a developer should be comfortable with using the tool. The minimal extra steps are not an issue to me.

Additionally, requiring additional steps harms the value of the starter project being the single point for common code/structure/files.

The intent would be for this to be included in the starter project as well.

The common docs situation does need to be resolved, and I think there may be a few alternative solutions that are more native and/or don't require additional steps.

How soon can a alternative be ready to use? What is the development effort required? This solution is ready now and connector maintenance needs to be sustainable. We can always migrate to a more optimal solution in the future.

The reality is that not everyone will understand Git submodules, and it could become a point of confusion or failure.

Regarding an alternative, no major additional development effort is required. I have made a POC implementation you can see at hms-networks/sc-java-maven-starter-project#56.

This POC implementation uses the previously mentioned Docusaurus plugin, and requires no new/additional steps of the developed. It also still makes use of this repository for common documentation, which makes sense anyways to help reduce the duplication of files, as you mentioned, which would occur when using the starter project as a template (if the common docs simply remained there).

[TomKimsey]

1. Use a Docusaurus plugin to import remote content from the relevant URL. Of interest is rdilweb/docusaurus-plugin-remote-content, which allows for remote content import without extra manual steps, but also includes support for adding/modifying/replacing content in the imported files in a customizable manner.

   • This could be added to the starter project and all repositories, referencing this repository, or it could be implemented to use the starter project as the 'content root' and cut out this repository. Either method works/is fine.

2. Create an npm module based out of this repository which would bundle the common documentation as a dependency that can be included in the starter project's yarn config, and in turn, the child repositories.

3. Use extensions library resources to bundle common docs files for use within connector/starter project child repositories. I'm not sure how the Docusaurus system would access the resources, but this is worth investigating as an alternative to requiring extra steps.

Git submodules are powerful, but add extra steps to build the documentation. This adds more potential/room for confusion in the development environment, where developers should be building the documentation regularly (to accompany changelog modifications).

My view is that using git submodules is normal and a developer should be comfortable with using the tool. The minimal extra steps are not an issue to me.

Additionally, requiring additional steps harms the value of the starter project being the single point for common code/structure/files.

The intent would be for this to be included in the starter project as well.

The common docs situation does need to be resolved, and I think there may be a few alternative solutions that are more native and/or don't require additional steps.

How soon can a alternative be ready to use? What is the development effort required? This solution is ready now and connector maintenance needs to be sustainable. We can always migrate to a more optimal solution in the future.

The reality is that not everyone will understand Git submodules, and it could become a point of confusion or failure.

Regarding an alternative, no major additional development effort is required. I have made a POC implementation you can see at hms-networks/sc-java-maven-starter-project#56.

This POC implementation uses the previously mentioned Docusaurus plugin, and requires no new/additional steps of the developed. It also still makes use of this repository for common documentation, which makes sense anyways to help reduce the duplication of files, as you mentioned, which would occur when using the starter project as a template (if the common docs simply remained there).

@alexjhawk
Yeah, i just tried the same exact thing with that plugin essentially and im pretty happy with it other than some weird behavior thats causing some looping but that might just be my config. My only comments are:

• I think it would be best to have documenation both in the starter project (General connector docs), but also have extensions lib specific documentation in the extensions lib (ex. Logging level docs, watchdog docs, etc)
• The plugin should target specific versions - https://raw.githubusercontent.com/hms-networks/sc-ewon-flexy-extensions-lib/v1.15.6/web-docs/docs

[TomKimsey]

@alexjhawk users will have the extra step of yarn add docusaurus-plugin-remote-content

[alexjhawk]

..........

@alexjhawk Yeah, i just tried the same exact thing with that plugin essentially and im pretty happy with it other than some weird behavior thats causing some looping but that might just be my config. My only comments are:

• I think it would be best to have documenation both in the starter project (General connector docs), but also have extensions lib specific documentation in the extensions lib (ex. Logging level docs, watchdog docs, etc)
• The plugin should target specific versions - https://raw.githubusercontent.com/hms-networks/sc-ewon-flexy-extensions-lib/v1.15.6/web-docs/docs

I was in the process of writing a very similar response. I definitely think versioning support will be necessary, and we could add the option to ScDocusaurusConfig.js

Regarding documentation in the starter project, I was thinking that the common documentation would be migrated to this repository. This avoids the versioned common docs files from being versioned in repositories that are created from the starter project template. The starter project would also use the plugin.

[alexjhawk]

@alexjhawk users will have the extra step of yarn add docusaurus-plugin-remote-content

The plugin inclusion is versioned as part of package.json/yarn.lock. Once the plugin is added, it is included in the normal yarn/npm/Docusaurus processes.

Nothing has changed with regard to installation/building of the documentation from where it currently is/was.

Edit

This is considering the common docs being located in this separate repository instead of the starter project. That allows us to add the plugin and import at the starter project level, which eliminates common docs entirely from being duplicated in to starter project child repos (and eliminates the extra step of installing the plugin at the child repo level)

[TomKimsey]

..........
@alexjhawk Yeah, i just tried the same exact thing with that plugin essentially and im pretty happy with it other than some weird behavior thats causing some looping but that might just be my config. My only comments are:

• I think it would be best to have documenation both in the starter project (General connector docs), but also have extensions lib specific documentation in the extensions lib (ex. Logging level docs, watchdog docs, etc)
• The plugin should target specific versions - https://raw.githubusercontent.com/hms-networks/sc-ewon-flexy-extensions-lib/v1.15.6/web-docs/docs

I was in the process of writing a very similar response. I definitely think versioning support will be necessary, and we could add the option to ScDocusaurusConfig.js

Regarding documentation in the starter project, I was thinking that the common documentation would be migrated to this repository. This avoids the versioned common docs files from being versioned in repositories that are created from the starter project template. The starter project would also use the plugin.

So do you agree that the extensions lib should include documentation? I think that would be ideal as if the extension lib is updated and functionality changes the application can just reference the documentation specific to the version its using starting at 1.15.X

[alexjhawk]

..........
@alexjhawk Yeah, i just tried the same exact thing with that plugin essentially and im pretty happy with it other than some weird behavior thats causing some looping but that might just be my config. My only comments are:

• I think it would be best to have documenation both in the starter project (General connector docs), but also have extensions lib specific documentation in the extensions lib (ex. Logging level docs, watchdog docs, etc)
• The plugin should target specific versions - https://raw.githubusercontent.com/hms-networks/sc-ewon-flexy-extensions-lib/v1.15.6/web-docs/docs

I was in the process of writing a very similar response. I definitely think versioning support will be necessary, and we could add the option to ScDocusaurusConfig.js
Regarding documentation in the starter project, I was thinking that the common documentation would be migrated to this repository. This avoids the versioned common docs files from being versioned in repositories that are created from the starter project template. The starter project would also use the plugin.

So do you agree that the extensions lib should include documentation? I think that would be ideal as if the extension lib is updated and functionality changes the application can just reference the documentation specific to the version its using starting at 1.15.X

Do you mean for all common docs, or just things related to the extensions library?

I absolutely agree that there is 'common' documentation related to the extensions library that should live in that repository. The starter project itself hosts a Docusaurus website as well, so those extensions library-related docs really should be included there anyways. We can then also import them to the starter project/child projects as necessary.

There is definitely a need for common docs in the extensions library, but also any that may be unrelated to the library should still be able to live in this repository (or similar one separate from the starter project).

[TomKimsey]

@alexjhawk , moved this back out of draft. This is where non extensions lib documents will go. Started version at 0.0.5 to match starter project.

[alexjhawk]

Shouldn't the README.md contents be updated to reflect the expected usage of this repository via the Docusarus plugin?

[TomKimsey]

yes, it would help if i saved that file.

[TomKimsey]

the installation and usage section have been removed entirely. Since the starter project is what will "implement" usage I dont think this needs to be documented here.

[alexjhawk]

@alexjhawk , moved this back out of draft. This is where non extensions lib documents will go. Started version at 0.0.5 to match starter project.

This works. I don't think the version number in this repository will be 100% matched to the starter project, though, so something like 1.0.0 or 1.0.5 also works.

[TomKimsey]

Adding @swapna-ragi as Ian is out of the office.