Purpose of establishing naming conventions:
- organization should be simple, clear, and logical
- need to be useful for end users
- organization of reports, queries should be logical and simple as possible; library technology right now has incredible complexity, explodes in every corner; would like to organize things so it's clear and simple for people coming in
- what we're really doing is taxonomy, which is both organization and naming
Elements relevant to naming:
Element | Value for Example Report | Description |
---|---|---|
Requirements ID | ID401 | |
JIRA Ticket | REP-103 | |
Name of Report |
| The report itself is focused on how the report is going to be used, not about how to get the data. This will also be the name of the JIRA issue. Report Naming Construct
Note: we should create a markdown file for each report that would live in a reports folder on GitHub; it should include original purpose of the report, description of the different queries, links to queries Can also link to report markdown files from the main ldp-analytics markdown file Question: how to keep track of work on things like this in JIRA |
Name(s) of query(ies) | ex.: Count Loans for Locations | The query is how to get the data. Possible naming convention for short names: verb, source data, function or maybe noun, verb, function example: Loans - Count by Location with Material Type Will likely create JIRA issues for all queries, maybe in LDP project; then can link from LDP query issue to report(s) that contain(?) that query Idea from Angela:
|
Short name(s) of query(ies) | ex.: count_loans_locations |
|
Umbrella category for report | Circulation | Group reports by the 5 most used apps of FOLIO that reports will be generated for:
just use umbrella category to organize reports, not to name them (could be the directory structure in LDP GitHub) use tagging (e.g., in GitHub?) to help organize reports, maybe to add original functional area to query |
Additional information that would be useful when browsing reports in, e.g., GitHub:
|
Clustering Reports
The report generation process has resulted in reports with a great deal of overlap. As part of the naming/prototyping process, the Reporting SIG and Report Prototype Working Group will be reviewing reports to identify reports that are exact duplicates or that have a similar purpose and many data elements in common. This process is called "clustering."
Clustering reports involves conversations with stakeholders and review by RPWG members. The basic steps are:
- Identify a member of the Reporting SIG to take a leadership role on the clustering project
- Clustering leader should identify one or more members of the relevant SIG (e.g., RA) to review the current reports
- Meet with SIG members (SMEs) to go through the reports one by one and brainstorm a "cluster name" - something that is short and summarizes the primary purpose of the report. Eventually, this name might need to conform to the naming conventions for "Report" listed above
- If reports are identified with similar properties, use the same cluster name for all of them. If the report is distinct, generate a new name.
- Also note any reports that may no longer meet the expectations for LDP reports, as well as any reports that may be more appropriate for a different functional area. Those reports should be removed or moved so they can be clustered with the correct functional area reports.
- A second pass through the clusters by another SME might be useful, especially if there were any questions about report purpose.
- Once all reports have a preliminary cluster, the clustering leader should review each cluster individually, with help from another RPWG member as needed.
- Take a look at the data elements required by all of the reports in a single cluster.