2023-02-03 - Comments on Current Specification
- Wes Brown
- Esther Ogunjimi
- Rachel Lawson (Unlicensed)
- Steve Conrad
General
GitBook / Markdown documentation standards documentation (in draft) to describe how to use images, links etc.
All BBs should have the same sections, with the same titles, in the same order
Example: All specs
Structure for each section should be common across BBs
Ex: Terminology on Payments vs IM, Key Digital Functionalities on Registration vs IM
Helping text from the BB template should not be included in the BB spec sections
Links to github must use a specific version or tag
Any links to any Google Docs that are “owned” by us shouldn’t be google docs. If they are controlled, possibly versioned, docs, they should be moved to GitBook and linked there. If they are uncontrolled, maybe Confluence is the best place? Or maybe even a blog post we can link to?
Let's decide where we are going to house and what will be used to create/edit diagrams and use it consistently
It needs to be something that we don't have to worry about losing access to, is versioned, can render nicely (Mermaid.js as default)
Terminology should be consistent between the BBs.
The sections do not need to be identical, but the definitions should all be done in the same format
Ex: Almost every BB has a different format. Some have lists, some are numbered, some use a table, some reference other terminologies (payments), etc
The Definition of individual terms should be the same across any BBs that use the term
Ex: Claim on DR vs ID
Do not abbreviate. Use Building Block instead of BB, the full name of the BB instead of any abbreviations, etc
The expected content and level of detail for the Key Digital Functionalities section needs to be defined and consistent across the BBs
Ex: ID vs Scheduler
Cross-Cutting Requirements should not include the architecture and security requirements, just links to those pages
Ex: IM
Specific items from the Arch or Security requirements should not be called out, unless different from those source requirements
Ex: DR
Cross-Cutting Requirements should define a common structure which should be consistent with the existing Arch and Security requirements
Likewise, the terms MUST, SHOULD, MAY, etc need to be used consistently
Template Feedback
Add content examples so that it is more clear what types of content each section should include and so that consistent formatting can be defined
Data Structures
Needs description
Need to define the common approach for describing data elements and the associated fields
Swagger is great but we want to have something in the spec as well
Workflows
More detailed guidance and examples on what a workflow is supposed to be in this context and how they should be described and modeled is needed
Other Resources
More detailed guidance and examples on the type resources that should be included and the format for including them
Key Decision Log
Is this needed along with the history that we can get in github?
If so, what constitutes a "key decision"?
What format should we use for the decisions?
Date ordering of the decisions should be defined
Future Considerations
What is the intent here? Should this really be a part of a Specification?
BB-Specific Feedback
Information Mediator IM-28: Update Information Mediator Specification for Version 1.0 releaseDone
2 Description IM-29: Rework Section 2 - DescriptionDone
The guidance from the TC on when to use an Information Mediator (documented n the non-functional requirements document) should also be documented or referenced here.
6 Functional Requirements IM-30: Rework Section 6 - Functional RequirementsDone
How does a network diagram relate to functional requirements?
Sub-bullet points in 6.1.3 Registration appear are not formatted properly
The level of detail does not match what is described in the template, lots of APIs and technical details are described
7 Requirements Clarification IM-31: Rework Section 7 - Requirement ClarificationDone
Should be moved to a sub-section of the Functional Requirements section
We should remove references to ‘Rooms’ as that is X-Road specific. We should instead talk about PubSub and how it should be implemented
8 Performance Requirements IM-32: Rework Section 8 - Performance RequirementsDone
Should be moved to a sub-section of the Cross-Cutting Requirements
9 Data Structures IM-33: Rework Section 9 - Data StructureDone
The github urls are not a specific version or tag
The field-level information has no details
Why do some things have github resources and others do not?
10 Service APIs IM-34: Rework Section 10 - Service APIsDone
Are the swagger links linking to a specific version or just the most recent?
Are the colors supposed to signify something? If so, create a legend
11 Workflows IM-35: Rework Section 11 - WorkflowsDone
The referenced workflows should be here instead of the Functional Requirements section
11.1 Where is the sequence diagram?
12 Key Decision Log IM-36: Rework section 12 - Key Decision LogDone
Order by date, either ASC or DESC but consistently
Level of "key decisions" here is not consistent
14 Annexes and Appendices IM-37: Rework/remove Section 14 - Annexes and AppendicesDone
This seems to be a catch-all for a lot of different kinds of content. This needs to be reviewed to see what really needs to be included in the spec, what can be moved into other sections within the spec, and should be moved to another location (Confluence)
Registration REG-65: Update Registration Specification for Version 1.0 releaseDone
This BB appears to be a functional description of one specific solution (UNCTAD eRegistrations) and not a general-purpose specification for Registration functionality. In my opinion, this specification does not adhere to the GovStack standards and needs significant revisions
3 Key Digital Functionalities REG-66: Rework Section 3 - Key Digital FunctionalityDone
The first functionality is a No-Code Development Platform? This doesn't seem related to registration functionality and is more of an implementation detail
Registration will involve the creation of forms – it will likely have a UX component. and we need to define how that process will work between the Registration BB, UI/UX and other BBs.
5 Functional Requirements REG-67: Rework Section 5 - Functional RequirementsDone
5.1.1 - Once again, No-Code seems like an implementation detail and not a requirement in registration specification
5.1.2 - Describing specific UI requirements should not be a requirement for a registration specification
5.2 - The spec should not be defining the specifics of how a UI should look/work, it should be defining the functionality that is required to provide the set of services needed (as defined by the Use Cases)
5.3 - What is the value of this table?
5.4 - This should be in the Cross-Cutting Requirements section
6 Data Structures REG-68: Rework Section 6 - Data StructuresDone
6.1 - Are these different from the standards defined in the Arch Requirements? If not, remove them
6.2 - What type of relationships are these and on what fields?
6.3 - There is no detail about what these resources should contain
7 Service APIs https://govstack-global.atlassian.net/browse/REG-69
7.1
The resource model should be in the Data Structures section
The APIs should be defined in the spec, not referenced in github
Is the Standards sub-section needed?
The core APIs for the registration process are not defined in this section. There is only a statistics API. I would expect to see APIs for submitting a registration, updating a registration, etc.
10 Key Decision Log https://govstack-global.atlassian.net/browse/REG-70
Dates should be included for decisions
11 Future Considerations https://govstack-global.atlassian.net/browse/REG-71
Should this comments section be in the spec?
Digital Registries https://govstack-global.atlassian.net/browse/DR-75
2 Description https://govstack-global.atlassian.net/browse/DR-76
This BB is described as a ‘no-code’ application with graphical interface to design databases. This is not true for digital registries – there are APIs defined and any candidates should provide that functionality through APIs. The APIs are described in the BB spec - we should remove references to no-code platform
6 Functional Requirements https://govstack-global.atlassian.net/browse/DR-77
Should functional requirements be organized around use cases? I would expect to see a list of the high-level functional requirements with details, irrespective of any use cases
7 Data Structures https://govstack-global.atlassian.net/browse/DR-78
7.1 - Are these different from the standards defined in the Arch Requirements? If not, remove them
7.2 - What type of relationships are these and on what fields?
7.3 - How do the referenced "Data Element" relate to the resources mentioned in 7.2?
8 Service APIs https://govstack-global.atlassian.net/browse/DR-79
The schemas should be in the Data Structures section
The github links are not valid
The swagger api definitions will not load
Standards info at the bottom is not needed
9 Workflows https://govstack-global.atlassian.net/browse/DR-80
This BB really has no workflows? I suspect we need a better definition for Workflow so it is more clear what is expected to be defined here
Key Decision Log https://govstack-global.atlassian.net/browse/DR-81
Missing
Appendix 1 & 2 https://govstack-global.atlassian.net/browse/DR-82
This should be moved into the Data Structures section
Identity https://govstack-global.atlassian.net/browse/ID-72
7 Data Structures https://govstack-global.atlassian.net/browse/ID-73
No field information for the data objects
8 APIs and Services https://govstack-global.atlassian.net/browse/ID-74
Change title to Service APIs to be consistent
Use embedded swagger for APIs like other BBs
8.2
This doesn't seem like the right place for this content. The Functional Requirements section could be a better fit
Use the same terminology for MUST, SHOULD, MAY, etc rather than Mandatory, Recommend, Specific, and optional
9 Workflows https://govstack-global.atlassian.net/browse/ID-75
I guess that these are ToDo?
Should the use cases be moved from Functional Requirements to Workflows, if that is what they really are?
11 Key Decision Log https://govstack-global.atlassian.net/browse/ID-76
Dates should be included for decisions along with deciders
Only "Key" decisions should be noted
Payments https://govstack-global.atlassian.net/browse/PAY-83
4 Payment Infrastructure Deployment Scenarios https://govstack-global.atlassian.net/browse/PAY-84
Why is this a dedicated section? It is not defined for any other BBs and should likely be put into another section or removed entirely (just kept as a Confluence page)
The BB spec should talk about the different components that make up a Payments BB (as several of the other BBs do). These can be borrowed from the G2PConnect work. And the Payments spec should clearly describe which components are in the scope of the BB. Throughout the BB, the spec should talk about component manages each part of a payment flow – switch, core banking, mobile money, account mapping, etc.
5 Key Digital Functionalities https://govstack-global.atlassian.net/browse/PAY-85
The key digital functionalities shouldn’t be rooted in use cases (G2P payments, etc). Should rather be core functionalities – like the ability to lookup an account based on foundational ID or mobile number.
6 Cross-Cutting Requirements https://govstack-global.atlassian.net/browse/PAY-86
The additional requirements are not detailed enough and/or not non-functional requirements
7 Functional Requirements https://govstack-global.atlassian.net/browse/PAY-87
Voucher management system is not a core component of payments. And we are missing things like account lookup (which is briefly described under voucher management) and core banking. Again, refer to G2PConnect
9 Service APIs https://govstack-global.atlassian.net/browse/PAY-88
There should be API definitions for each component - payment switch, account mapping, core banking functionality, etc.
The APIs are very incomplete – we should have clear APIs defined for core use cases. Mojaloop has well-documented flows that can be used to extract what APIs would be needed. Or can reference the Mifos PaymentHub as well
9.1, 9.2, 9.6 - Where are the API endpoints defined?
9.3, 9.5 - Use embeded swagger APIs
9.4 - We should not reference other unversioned specifications. What happens if mojaloop changes their spec?
9.6.6.1 - We don't need to document the status codes unless they deviate from the HTTP standard (which they shouldn't)
10 Workflows https://govstack-global.atlassian.net/browse/PAY-89
Where is 10.1?
If a workflow has different options, shouldn't they each be considered a separate workflow?
Does the level of detail for these workflows contain too much internal payment BB descriptions? Other BBs shouldn't need to know about the internals of how payment systems work
There is a ton of content here but I'm not sure that this is the right place for it (or if this content really needs to be so detailed)
11 Other Resources https://govstack-global.atlassian.net/browse/PAY-90
Standards are not needed here
GovStack Resources do not need to be linked here
Google Drive documents should not be linked
11.3 The links to this content should be located where they are referenced within the spec
12 Key Decision Log https://govstack-global.atlassian.net/browse/PAY-91
Dates should be included along with deciders
Comments seems out of place here (and in the spec in general)
Consent https://govstack-global.atlassian.net/browse/CON-75
4 Key Digital Functionalities https://govstack-global.atlassian.net/browse/CON-76
Remove links to Google Drive docs in functionalities
5 Cross-Cutting Requirements https://govstack-global.atlassian.net/browse/CON-77
Remove content from Arch Requirements
7 Data Structures https://govstack-global.atlassian.net/browse/CON-78
7.1 Convert the diagrams to align to similar relationship diagrams from other BBs
7.2 Does this belong in this section?
7.3 Are these different from the standards defined in the Arch Requirements? If not, remove them
7.4 Just put the models here, don't reference another document
8 Service APIs https://govstack-global.atlassian.net/browse/CON-79
The APIs need to be listed here and included as embedded swagger APIs
Comments and suggested edits should happen on this page, not in a linked spreadsheet
The github link just goes to the root repo, not to an OpenAPI spec
9 Workflows https://govstack-global.atlassian.net/browse/CON-80
The numbering is off here, 4 should be 9 and it should start with 9.1 instead of 4.4
Embed the diagrams so that they are viewable within the spec
10 Other Resources https://govstack-global.atlassian.net/browse/CON-81
Use a sentence rather than NA, something like "There are no other resources for the Consent Building Block."
11 Key Decision Log https://govstack-global.atlassian.net/browse/CON-82
This looks great, could also include who made the decisions
Workflow https://govstack-global.atlassian.net/browse/WF-32
4 Key Digital Functionalities https://govstack-global.atlassian.net/browse/WF-33
More detail is needed here, at least to be consistent with the other BBs and how the BB template describes this section
5 Cross-Cutting Requirements https://govstack-global.atlassian.net/browse/WF-34
Remove content from Arch Requirements
6 Functional Requirements https://govstack-global.atlassian.net/browse/WF-35
Referenced image is missing
Some markup issues
For Future Consideration should not be included in the spec
7 Data Structures https://govstack-global.atlassian.net/browse/WF-36
Remove future support from spec
While linking to a specific version in swaggerhub is fine, I think that the spec should also contain the schema as well
8 Service APIs https://govstack-global.atlassian.net/browse/WF-37
The APIs need to be listed here and included as embedded swagger APIs
In discussion topics and future plans should not be included in the spec
9 Workflows https://govstack-global.atlassian.net/browse/WF-38
Invalid url near the top
Why are we organzing around use cases for workflows? The content here should be organized around functionality that relates to other BBs
10 Other Resources https://govstack-global.atlassian.net/browse/WF-39
Discussions should not be in the spec
UI Examples
The linked images are not loading
This seems like it would better be located in the Workflows or Functional Requirements section
11 Key Decision Log https://govstack-global.atlassian.net/browse/WF-40
Only include decisions that impact the spec, not discussions/thoughts or things that may be done in the future
Messaging https://govstack-global.atlassian.net/browse/MSG-42
4 Key Digital Functionalities https://govstack-global.atlassian.net/browse/MSG-43
Need additional detail and evaluation of the functionalities listed. The supposed functionalities mentioned are not specific enough
5 Cross-Cutting Requirements https://govstack-global.atlassian.net/browse/MSG-44
These need to be reviewed, there is a lot of very opinioned requirements here that may not be needed
6 Functional Requirements https://govstack-global.atlassian.net/browse/MSG-45
6.2 This doesn't seem to belong in this section
6.3 This doesn't seem to belong in this section
6.5 Remove this section from the specification
7 Data Structures https://govstack-global.atlassian.net/browse/MSG-46
7.2 Are these different from the standards defined in the Arch Requirements? If not, remove them
7.3 The schemas for all messaging-related elements should be defined here
8 Service APIs https://govstack-global.atlassian.net/browse/MSG-47
Nothing is defined here
9 Workflows https://govstack-global.atlassian.net/browse/MSG-48
9.1 - This can be removed
9.2
The sub-item numbering appears to be off
The sequence diagram is not displaying properly
9.3
The sub-items are numbered incorrectly
I am unclear what this content is supposed to describe
The content here needs some significant review and editing
10 Other Resources https://govstack-global.atlassian.net/browse/MSG-49
This content should likely be in the workflow and aligned to the workflow format, once defined
11 Key Decision Log https://govstack-global.atlassian.net/browse/MSG-50
This is not a meeting notes page, that content belongs in Confluence not in a spec
Scheduling https://govstack-global.atlassian.net/browse/SKD-4
7 Data Structures https://govstack-global.atlassian.net/browse/SKD-5
Standards - Are these different from the standards defined in the Arch Requirements? If not, remove them
Data Elements is lacking detail (eg field type)
8 Service APIs https://govstack-global.atlassian.net/browse/SKD-6
API Standards do not need to be included unless they are different from the Arch requirements
The APIs need to be listed here and included as embedded swagger APIs
9 Workflows https://govstack-global.atlassian.net/browse/SKD-7
This is nothing like any of the other Workflow sections, need to decide on a format
Workflows should not, in my opinion, be organized around specific use cases
Perhaps this content can be used as the basis for the Use Case Example Implementations?
10 Other Resources https://govstack-global.atlassian.net/browse/SKD-8
Links to other GovStack documents are not needed
11 Key Decision Log https://govstack-global.atlassian.net/browse/SKD-9
Include dates and who was involved in each decision
Tasks