finos / finos/architecture-as-code
Proposal to add "Converting Controls to CALM" Practicioners Guide
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 38
Description
Feature Proposal
Target Project:
The documentation site, specifically the Practitioner's Guides.
Description of Feature:
This feature involves creating a generalized documentation resource that guides users on converting their existing, non-functional controls into CALM controls.
Because this topic comes up frequently during office hours and in the community, creating a single reference link to share with people will significantly streamline support.
The addition is proposed to take the form of a new Practitioner's Guide.
User Stories:
As a project Evangelist/maintainer, I want a single documentation link explaining how to convert controls into CALM controls so that I can easily share it with users who frequently ask this question.
As a practitioner/user, I want to read a dedicated guide on converting my organization's non-functional controls into CALM controls so that I can easily translate them into a valid CALM schema.
Current Limitations:
The topic of converting controls into CALM controls comes up repeatedly, indicating a persistent gap in the current instructional resources.
There is currently no single documentation link or generalized guide that maintainers can quickly share with users to explain this process, leading to duplicated effort when answering questions.
Proposed Implementation:
Technical design considerations: Create a new markdown file in the documentation repository to serve as a Practitioner's Guide.
API changes: None.
Data model changes: None.
Dependencies on other components: None.
Alternatives Considered:
Continuing to answer questions about control conversion on an ad-hoc, one-on-one basis, which is inefficient and time-consuming because the topic is brought up so frequently by the community.
Testing Strategy:
Review the written guide for clarity, accuracy, and completeness before publishing.
Ensure the guide successfully provides a generalized framework for control conversion that can be understood by users across different organizations.
Documentation Requirements:
This entire feature request is to generate a new documentation page.
A new Practitioner's Guide needs to be created, reviewed, and linked within the existing documentation site's navigation.
Implementation Checklist:
[ ] Design reviewed and approved
[ ] Implementation completed
[ ] Tests written and passing
[ ] Documentation updated
[ ] Relevant workflows updated (if needed)
[ ] Performance impact assessed
Additional Context:
Briefly discussed during https://github.com/finos/architecture-as-code/issues/2425 where @rocketstack-matt suggested this should be a Practicioners Guide
Contributor guide
Assessment
This issue has not been assessed yet.