How can we make the documentation-framework easier to work with?

[jpuzz0]

In general, making changes to the documentation-framework can take a lot of time, where most of that time is spent trying to understand how everything is currently setup/working.

If we continue to add logic to an already confusing package, we potentially add more layers of confusion and incrementally make the package more difficult to work with.

Some questions to consider:

• Is this just a matter of improving/creating documentation explaining how the package works and integrates with all other things Patternfly?
• Should we consider refactoring/cleaning up the package? Use typescript?
• Should we add integration and unit testing?
• Should we consider new or lean further into already used 3rd party packages to achieve similar functionality for certain aspects of the package?
• Can clean up/refactoring lead to a resolution of the issue described here?

[wise-king-sullyman]

Should we consider refactoring/cleaning up the package?

Based on the trends I've seen so far I think that if we don't do some major refactoring and cleaning up we will continue to run into difficult to understand issues related to the docs framework. Additionally as you've highlighted the process of making changes in the docs-framework easily becomes a painful affair.

Use typescript?

TS would improve the developer experience working on the docs framework massively imo.

Should we add integration and unit testing?

I think that good test coverage in the docs framework would help substantially in keeping it robust, well documented, and generally easy to work on in the future. Though while I think adding testing would be well worth the time investment I personally wouldn't prioritize that effort over improving the testing situation in our other repos with packages that external consumers rely on.

Should we consider new or lean further into already used 3rd party packages to achieve similar functionality for certain aspects of the package?

Moving more functionality to 3rd party packages rather than building our own approach to so many problems would likely make the docs framework a lot more manageable. It would also significantly lighten the workload for all of the previously mentioned initiatives.

Can clean up/refactoring lead to a resolution of the issue described

If the general clean up doesn't fix the issue it would still most likely make the issue much easier to resolve.