Naming Conventions for Reports and Queries

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	Circulation Transaction Detail Circulation Transactions Loans with Material Type Circulation Transactions with Bibliographic Detail Loans with Material Type and Bibliographic Detail Loans with Item Detail	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 by = filter or focus; appropriate for reports that aggregate transactions, not for transaction-level reports with = what the report includes, details only include as many extra clauses as is necessary to distinguish this report; if "bibliographic detail" is expected, don't need to list it 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 example: count loans for locations 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: for noun, what is each row in the resulting table? is it a loan? a general circ transaction? a patron? for verb, either count or list? for modifiers, focus on with and by? only add ones that change between versions of queries?
Short name(s) of query(ies)	ex.: count_loans_locations	needs to be machine-readable, usable as a variable underscores are better than dashes because some programs don't like dashes in variable names may or may not need to look like the regular name; might need to be shorter use as GitHub folder name if adding something to indicate aggregation (_counts, _detail), add to end so you can sort like with short name, maybe use verb after nouns so things can be sorted by main topic of interest
Umbrella category for report	Circulation	Group reports by the 5 most used apps of FOLIO that reports will be generated for: users circulation (check out, check in, requests) inventory finance and orders resource management 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: date of query tag indicating original functional area

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.
Send final clusters back to functional area SIG for prioritization.
Once all reports have a cluster assignment, the clustering leader should review each cluster individually, with help from another RPWG member as needed.
1. Take a look all of the reports in a single cluster.
2. Verify that reports all have similar enough purpose to be called a cluster.
3. Compile a full list of the data elements required by the clusters.
4. Specify any major differences between the reports requested that might require slightly different queries. For example, if one report requests individual transactions and another requests aggregate counts, it might be worth specifying two separate queries for that cluster.
Each cluster will need a UXPROD issue to organize work on the required query or queries. Only a PO or a designated Reporting SIG member can create issues in the UXPROD project, so you will need to send the following information for each cluster:
1. Name of cluster
2. Full list of elements required for a comprehensive query that covers all cluster reports
3. Subqueries that might be useful, in addition to the comprehensive query
4. Final list of the REP issues that should be associated with this cluster
After the clusters are finalized, the clusters can be treated like individual reports - they can be prioritized by the Reporting SIG and then assigned to members of RPWG for prototyping and query development.