From c6af675026e0146cb71322ec1ec8f88342ac1f7a Mon Sep 17 00:00:00 2001 From: JW Jacobson <116485484+jwjacobson@users.noreply.github.com> Date: Thu, 20 Jun 2024 12:32:55 -0400 Subject: [PATCH] Add further rebuilt docs --- docs/about/fields.rst | 40 +++++++++++++++++++++++++++++++++++++--- docs/using/playing.rst | 2 +- docs/using/searching.rst | 10 ++++++---- 3 files changed, 44 insertions(+), 8 deletions(-) diff --git a/docs/about/fields.rst b/docs/about/fields.rst index cc8dd95..32e38aa 100644 --- a/docs/about/fields.rst +++ b/docs/about/fields.rst @@ -1,11 +1,45 @@ Tune fields ============== -In defining the fields I've tried to balance between making the app useful and giving freedom to the user. Here I describe my thinking behind each. In some cases it only applies to the Public repertoire, as the user can do what they want. +In defining the fields I've tried to balance between making the app useful and giving freedom to the user. Here I describe my thinking behind each. In some cases my descriptions only apply to the Public repertoire, as the user can do what they want with their own tunes. + +In general I'm open to revising the prescriptive aspects of any of these in dialogue with users, so reach out if you'd like to see any changes or additions. Title ------ -Title is the only required field since it's what identifies a tune. There are situations where any of the other fields might be left blank, but not title. +A tune's unique identifier, Title is the only required field. Composer -------- -I index all composers by last name as a way of showing equal respect to jazz and popular tune composers. At the same time, \ No newline at end of file +I index all composers by last name as a way of showing equal respect to jazz and popular tune composers. At the same time, jazz first names and nicknames (Bird, Miles, etc.) are recognized "behind the scenes" when searching and will be appropriately converted and retrieved. + +Key +----- +Key can be left blank, or you can fill it with 'none' or 'atonal'. There can only be one Key; in tonal tunes without an obvious "main" key I leave this blank and put all the keys in Other Keys. A '-' after the letter denotes minor; unadorned is major. + +Other Keys +----------- +Any keys a tune modulates to besides the main key go here. + +Form +----- +I've opted not to include primes etc. to make the form categories as broadly applicable as possible. For example, "I Remember You" is classified as AABA, not AABA'. + +Style +------ +'Standard' is for pop or Broadway tunes played by jazz musicians, while 'jazz' is for tunes written by jazz musicians. Other stylistic descriptors can be added as tags (eventually). + +Meter +------ +This has a default value of 4 for convenience since almost every standard is in 4. + +Year +----- +For a lot of the jazz tunes the year is when the first album featuring the tune came out. Let me know if you have more accurate knowledge! + +Last Played +------------ +The date you last played a tune. I try to keep as many out of the "haven't played in 3 months" category as I can. + +Knowledge +---------- +The broad delineation between "know", "learning", and "don't know" seems most useful to me. As I use it, "know" means you can play the tune at the drop of a hat with no hesitation and no chart. Otherwise it's "learning". "Don't know" is a placeholder for tunes you want to learn. \ No newline at end of file diff --git a/docs/using/playing.rst b/docs/using/playing.rst index da5375b..0541b08 100644 --- a/docs/using/playing.rst +++ b/docs/using/playing.rst @@ -3,7 +3,7 @@ Playing tunes You can 'play' tunes by clicking the **play** button on the homepage, or by using the **Play** page, accessed from the navbar. -The **Play** page will recommend a tune to play based on your search results (see XX for more on searching). It will not suggest tunes with a Learning value of "don't know." If you submit an empty search if will use your whole repertoire (except the ones you don't know). +The **Play** page will recommend a tune to play based on your search results. It will not suggest tunes with a Learning value of "don't know." If you submit an empty search if will use your whole repertoire (except the ones you don't know). Regularly updating your plays is the most useful feature of the app! diff --git a/docs/using/searching.rst b/docs/using/searching.rst index b647feb..fdbdebf 100644 --- a/docs/using/searching.rst +++ b/docs/using/searching.rst @@ -1,14 +1,16 @@ +.. _searching: + Searching your repertoire ========================= The **Home**, **Play**, and **Public** pages all contain a search box that uses the same logic. -By default, every field is searched for your search term. If you enter multiple terms, the search uses AND logic. For example, if you search **monk** you will see all tunes with monk in any fields (usually composer). If you search **monk bud**, it will only return "In Walked Bud" (assuming it's in your repertoire). +By default, every field is searched for your search term. If you enter multiple terms, the search uses AND logic. For example, if you search ``monk`` you will see all tunes with monk in any fields (usually composer). If you search ``monk bud``, you will only see "In Walked Bud" (assuming it's in your repertoire). -Jazz composer names have built-in substitutions using their nicknames or first names, so searching **miles** will return Miles Davis tunes, **bird** will return Charlie Parker tunes, etc. +Jazz composer names have built-in substitutions using their nicknames or first names, so searching ``miles`` will return Miles Davis tunes, ``bird`` will return Charlie Parker tunes, etc. -Use a **-** before a term to exclude it from the search results. +Use a ``-`` before a term to exclude it from the search results. -You can also use the format **field:term** to search a specific field. Currently supported fields are **title**, **composer**, **key** (the key column, a tune's main key), **keys** (both the Key and Other Keys columns), **form**, **style**, **meter**, and **year**. It is most useful for key, keys, and form. +You can also use the format ``field:term`` to search a specific field. Currently supported fields are **title**, **composer**, **key** (the key column, a tune's main key), **keys** (both the Key and Other Keys columns), **form**, **style**, **meter**, and **year**. It is most useful for key, keys, meter, and form. The **haven't played in** dropdown lets you filter by how long it's been since you've played a tune. This allows you to easily target tunes at the highest risk of being forgotten.