[MODUSERS-119] Missing or incomplete documentation of data attributes in mod-users Created: 10/Oct/18 Updated: 14/Mar/22 Resolved: 14/Mar/22 |
|
| Status: | Closed |
| Project: | mod-users |
| Components: | None |
| Affects versions: | None |
| Fix versions: | 18.3.0 |
| Type: | Task | Priority: | P3 |
| Reporter: | Nassib Nassar | Assignee: | Julian Ladisch |
| Resolution: | Done | Votes: | 1 |
| Labels: | back-end, documentation | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Issue links: |
|
||||||||||||||||
| Sprint: | CP: sprint 135 | ||||||||||||||||
| Story Points: | 1 | ||||||||||||||||
| Development Team: | Core: Platform | ||||||||||||||||
| Description |
|
High priority APIs:
Acceptance criteria:
Two examples of attribute documentation: I.
Attribute name: username
Description: The user's login name. This also serves as an unique,
human-readable identifier for the user.
Domain: String of alphanumeric Unicode characters, beginning with
an alphabetic character. Maximum of 16 characters.
Required: Yes
References: N/A
Other constraints: Unique, but may be reused after the user is deleted.
II.
Attribute name: patronGroup
Description: The patron group that the user belongs to.
Domain: UUID
Required: Yes
References: "User Groups" /groups/{groupId} (e.g. mod-users)
Other constraints: None
These examples are intended not to prescribe a documentation format or style but to illustrate further the basic documentation content being requested. |
| Comments |
| Comment by Nassib Nassar [ 06/Nov/18 ] |
|
For an initial round, the following interfaces would be most useful: mod-users: /groups |
| Comment by Julian Ladisch [ 27/May/21 ] |
|
Nassib Nassar: Please review. Detailed documentation has been published on https://dev.folio.org/reference/api/#mod-users . This includes Please review and give feedback whether this is sufficient and this issue can be closed, or list the information that is still missing. |
| Comment by Nassib Nassar [ 29/May/21 ] |
|
Thank you. We will ask the Reporting SIG (via Angela Zoss) if they would review this, as they are the consumers of the documentation. |
| Comment by Angela Zoss [ 13/Jul/21 ] |
|
Thank you! We have reviewed and have a few suggestions, all for the mod-users/users interface:
|
| Comment by Charlotte Whitt [ 08/Mar/22 ] |
|
Marc Johnson - based on the feed back from Angela Zoss 7/13/2021 (see above) then this ticket looks like it should be moved back In progress. Do you agree? |
| Comment by Marc Johnson [ 08/Mar/22 ] |
Sure. Given that Julian Ladisch did the original work that the review was requested of, I don't think I (or the Prokopovych team) are the right audience to receive the feedback. I suggest assigning this work to Julian Ladisch and the Core Platform team given they have taken an active interest in it. Type of Documentation Requested I will say that the API documentation format that the module users is not well suited to full documentation of the sort that Nassib Nassar and Angela Zoss are asking for. The space available to use is a single piece of text that could get unwieldy if it is long. It cannot provide the kind of structured documentation that Nassib Nassar uses in the issue description.
I think this level of documentation about the domain being modelled by FOLIO is better suited to the official FOLIO documentation, that is intended to be user facing, rather than the brief API documentation. Similarly, for the type field, I don't think developers (who tend to be asked to add fields without being given the context of the domain) are the appropriate folks to describe what kinds of types an organisation my define for it's users especially given this field is free entry text. |
| Comment by Julian Ladisch [ 10/Mar/22 ] |
|
Angela Zoss Please review the pull request: https://github.com/folio-org/mod-users/pull/238/files |