Merge pull request #4736 from cielf/user-docs-cont-vii

User docs -- First words pass is done, working on todos

Gemfile.lock

@@ -798,4 +798,4 @@ DEPENDENCIES
   webmock (~> 3.24)
 
 BUNDLED WITH
-   2.5.21
+   2.5.22

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2024_08_30_015517) do
+ActiveRecord::Schema[7.1].define(version: 2024_10_02_205346) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "plpgsql"
 

docs/user_guide/bank/account_management.md

@@ -0,0 +1,27 @@
+DRAFT USER GUIDE
+# Account Management
+
+## Logging out
+You can log out be clicking your name in the top right corner, then clicking 'Log out'.
+
+[TODO: Navigational screenshot]
+
+
+## Account settings
+You can change your name, email, and password in account settings.  Any of these changes will need your current password.
+Click your name in the top right corner,  then "Account Settings"
+[TODO:  Navigational screenshot]
+Provide your updated information, including your current password,  then click save.
+If you want to change your password, you can do it here -- click the Change Password section to show the new password and confirmation fields.
+[TODO: screen shot]
+[TODO:  Actually test this out.  *I've* never used it.]
+
+Then click save.
+
+## My organization
+If you are an org admin,  you can also manage your organization and users through the top-right menu.  This goes to the same screen as clicking on "My Organization" in the left-hand menu.  For details, see [Customization](getting_started_customization.md) and [User Management](user_management.md)
+[TODO:  Add switching to partner ]
+
+
+
+[Prior: User management](user_management.md) [Next: Asking for changes](asking_for_changes.md)

docs/user_guide/bank/asking_for_changes.md

@@ -1,9 +1,11 @@
 # Asking for changes
 
-Although we are a small team with a long list of tweaks and improvements that we are working toward,  we do welcome ideas for how Human Essentials can support your work better.  
+We welcome ideas for how Human Essentials can support your work better.
 
 The best ways to get those to us are through the Slack channel or by coming to the Stakeholder Circle and raising them there.
 
 The Stakeholder Circle has the advantage of being able to talk live to other banks *and* the development team in the same space.   We've had a lot of "Oh, we didn't realize that" moments in these meetings that directly result in changes to the system.
 
-(The Slack channel, on the other hand, is open every day.)
+(The Slack channel, on the other hand, is open every day.)
+
+[Prior: Signing out](top_right_menu.md)

docs/user_guide/bank/community_donation_sites.md

@@ -1,6 +1,9 @@
 # Donation Sites
 
-Donation sites are places where people drop off donations. You can manage the sites' information on the "Donation Sites" page under the "Community" section. 
+Donation sites are places where people drop off donations. 
+
+## The donation site list
+You can manage the sites' information on the "Donation Sites" page under the "Community" section. 
 
 ![Donation Sites](images/community/donation_sites/donation_sites.jpg)
 
@@ -16,6 +19,7 @@ Note that the donation site and address fields are mandatory while the contact n
 
 You can also use the "+ New Donation Site" button which renders a form for you to fill in details of a new donation site.
 
+
 ![Add Donation_Site](images/community/donation_sites/add_new_donation_site.jpg)
 
 After saving the site's details there will be a new row on the Donation Sites page.
@@ -36,10 +40,14 @@ Clicking on the "Edit" button beside a donation site in the donation site list l
 
 Use the "Deactivate" button to delete information about a donation site that is no longer active.
 
+##### (NB) at time of writing there is no way for you to undo this.
+
 ![Deactivate Donation Sites](images/community/donation_sites/deactivate_donation_site.jpg)
 
 ## Exporting Donation Sites
 
 You can export the active donation sites by clicking on the "Export Donation Sites" button. This will provide a .csv file containing the name, address, and contact information for each active donation site.
 
-![Export Donation Sites](images/community/donation_sites/export_donation_sites.jpg)
+![Export Donation Sites](images/community/donation_sites/export_donation_sites.jpg)
+
+[Prior: Product Drive Participants](community_product_drive_participants.md)[Next: Vendors](community_vendors.md)

docs/user_guide/bank/community_manufacturers.md

@@ -22,4 +22,4 @@ Click on "View" for more details about the manufacturer which shows the date of
 
 Click the "Edit" button to edit the manufacturer's name.
 
-![Edit Manufacturer Details](images/community/manufacturers/edit_manufacturer.jpg)
+[Prior: Vendors](community_vendors.md)[Next: Exports](exports.md)

docs/user_guide/bank/community_product_drive_participants.md

@@ -37,4 +37,6 @@ Click the "Edit" button to edit the participant's details.
 You can export all the participants by clicking on the "Export Product Drive Paticipants" button.
 Currently we are not providing all the participants' details in the export.
 
-![Export Drive Participants](images/community/product_drive_participants/export_participants.jpg)
+![Export Drive Participants](images/community/product_drive_participants/export_participants.jpg)
+
+[Prior: Product Drivess](community_product_drives.md)[Next: Donation Sites](community_donation_sites.md)

docs/user_guide/bank/community_product_drives.md

@@ -0,0 +1,96 @@
+DRAFT USER GUIDE
+# Product Drives
+Many banks hold seasonal or one-off events where they are seeking donations.  In Human Essentials, Product drives help manage those events by providing a way to link specific donations to the events.
+
+[TODO:  For consistency, I would remove 'New Product Drive' from the lhs, and change "All Product Drives" to "Product Drives]
+
+## Product drives list
+To see all your product drives, click on "Community", then "All Product Drives" in the left-hand menu.
+
+This presents a filterable list of all your product drives, including the following fields:
+- Product Drive Name
+- Start Date
+- End Date (this is optional)
+- Held Virtually?
+- Quantity of Items
+- Variety of Items
+- In-Kind Value (TODO:  Fix spelling in header)
+- Actions (only view at the moment)
+
+The list initially shows all the product drives starting in the current year. 
+
+[TODO:  NAvigation screenshot]
+
+
+
+[TODO:  Is that right,  or is it all product drives that are at least partly in the current year?   It probably should be the latter]
+
+### Filtering you product drives list
+The product drives list is filterable by any of the following. 
+- Product drive name
+- Item category
+- Date range (by starting date)
+
+[TODO:  confirm how the date range works.]
+
+Provide the information you want to filter by, then click "Filter".  Clicking "Clear Filters"  will return the list to its defaults.
+
+## Adding a product drive
+To add a product drive, either:
+a) click "Community", then "New Product Drive" in the left hand menu, or
+b) click "+New Product Drive" in the Product Drives list
+[TODO:  Navigation screenshot]
+
+Either will bring up this screen, which contains all the fields you can specify for a new product drive:
+- Name
+- Start Date
+- End Date (this is optional)
+- Product Drive is Virtual? (check this if it's a virtual drive)
+
+[TODO: Screenshot]
+[TODO:  Styling of "Create product drive" -- button should be white on green] 
+
+## Viewing your product drive
+To view a specific product drive, click the "View" button beside it in the product drives list.
+[TODO: Navigational Screenshot]
+[TODO: Screenshot]
+This will bring up the product drive view, which includes informtation about both the donations for the product drive, and the participants in the drive, in addition to the basic information about the product drive itself.
+Basic info:
+- Name
+- Start Date
+- End Date
+[TODO:  Move the "Make a correction" button up to below the basic information, not below the donations]
+Information about each donation:
+- Donation ID -- this is a number the system applies to each donation
+- Product Drive Participant
+- Storage Location
+- Quantity (this is the total number of items)
+- In Kind Value
+For each product drive participant associated with this product drive:
+- Business Name
+- Contact Name
+- Phone
+- Email
+- Address
+- Items for this Drive (number of items for this drive)
+- Total Items (for all drives)
+- Comment
+
+You can also make a correction to your product drive or delete it from this page.
+
+#### NB -- DO NOT DELETE your product drive if it has donations in it.  It will not go well.
+
+##  Modifying your product drive
+If you want to edit the base information in a product drive, you can do that by clicking "Community", then "All Product Drives" in the left-hand menu,  then clicking "View" beside the product drive you wish to modify, and then clicking "Make a correction".
+This will bring up the basic information for your product drive,  You can rename it, change the dates, or change whether it is a virtual drive.
+Then click "Update Product drive" to save your changes.
+
+[TODO: Screenshot]
+
+## Exporting product drives
+To export your currently filtered product drives,  click "Export product drives" on the Product Drives List
+
+[TODO:  Navigation Screenshot]
+
+[Prior: Transfers](inventory_transfers.md)
+[Next: Product Drive Participants](community_product_drive_participants.md)

docs/user_guide/bank/community_vendors.md

@@ -39,4 +39,6 @@ Click the "Edit" button to edit the vendor's contact information.
 You can export all the vendors by clicking on the "Export Vendors" button.
 Currently we are only providing the vendors' contact information in the export.
 
-![Export Vendors](images/community/vendors/export_vendors.jpg)
+![Export Vendors](images/community/vendors/export_vendors.jpg)
+
+[Prior:  Donation Sites](community_donation_sites.md)[Next: Manufacturers](community_manufacturers.md)

docs/user_guide/bank/essentials_dashboard.md

@@ -26,3 +26,4 @@ This lists items whose *bank-wide* inventory has fallen below the recommended or
 
 For help on setting those levels, see [Inventory Items](inventory_items.md).  If you haven't set those levels, the items will not appear on this list, even if you have no inventory.
 
+[Prior: User management](getting_started_user_management.md) [Next: Donations](essentials_donations.md)

docs/user_guide/bank/essentials_distributions.md

@@ -1 +1,88 @@
-Not yet written
+
+DRAFT USER GUIDE
+# Distributions
+Distributions are where you record what you allocate to your partner agencies.
+
+Some things to know:
+* Once you save a distribution,  those items are allocated to the partner, and are no longer part of your inventory in the system.
+* If you are accepting requests from partners,  you initiate the distribution by "fulfilling" the partner request. (see [Requests](essentials_requests.md))
+
+## Seeing a list of your distributions
+To view a list of your distributions,  click on 'Distributions' in the left hand menu.  This brings up a list of all your distributions for the current year.   You can change what distributions are displayed using the distribution filters at the top of the list.
+
+
+### Filtering the distribution list
+
+[TODO: Insert mini screenshot of just the filtration section here]
+
+When you have been using human essentials for a few months, your distribution list may grow to the point that you really need to be able to narrow things down to find a particular distribution.
+
+To help with that, you can filter the distribution list by several aspects: item, item category, partner, source inventory (i.e. storage location) and distribution status, and date range.
+If you pick several things,  you will get only the distributions that match all of them.
+
+
+Except for date range,  all the filters are specified by picking from a drop-down list as follows
+Item: all active items (TODO:  Confirm -- is it just active or are the inactives there too?).  This will filter to only the distributions that contained that item.
+Item category:  Item categories (as specified in [Items & Inventory | Item Categories](inventory_items.md)) [TODO:  point right to categories section].  This will filter the list to the distributions that contain items that are in the chosen item category.
+Partner:  This will filter the lists to just the distributions to the chosen partner.
+Source Inventory:  This will limit the list to the distributions from the chosen storage location.
+Status:  Distributions can be Scheduled or Complete. This will limit the list to those with the given status.
+Date range:  This is based on the "Distribution date and time" field, ignoring the time.  Date range is selected using a little calendar gizmo with several presets, or by typing the date range into the field.    We highly recommend using the calendar gizmo instead of typing in the field, as the text field is very particular as to the format - we have a few people experiencing mismatches there every month.
+
+When you have have selected your filters,  press "Filter" to do the filtering.  If you still have too many distributions showing, you can add another filter to narrow it down further.
+
+Clicking "Clear filters" will blank out the filters that are drop-down selection, and revert the date range to the current year.
+
+## New Distribution
+To enter a new distribution,  click on "New Distribution" in the Distributions list.
+
+Here, you will enter some information about the whole distribution,  then add the all the items that make it up.
+The fields include:
+- Partner (mandatory)
+- Distribution date and time -- this is defaulted to midnight of the current day.  If you want to change it (if, for example, you have a specific time you are scheduling the pickup for), we recommend you use the little calendar gizmo at the right of the field.
+  [question:  does send email reminder the day before appear based on an organization flag?]
+- Send email reminder the day before  --> causes an email to be sent the day before
+  [question:  what happens if we check this and it's today?]
+- Agency representative - for information only  [TODO:  is this defaulted from the chosen partner?  It could be.. but do we?]
+- Delivery method -- we default this to pickup because it's the most common across banks.
+- From storage location:  The storage location the distribution is coming from.  Obviously mandatory.
+- Comment
+- All the items:
+- For each item:
+    - If you have set up barcodes for items, you can just boop the item in.  Otherwise,  select the item from the list, and enter the quantity
+    - [TODO:  Totally rewrite this bit for packs]
+## Exporting Distributions
+To export your distributions, click "Export Distributions" on the distributions view.  This will include all the top-level information, and a column [or more, if you use custom units] for each item in the distribution,  in alphabetic order.   It will include all the distributions within the filter you have already applied.
+[TODO:  add navigational screenshot and sample csv]
+## Viewing a Distribution
+To view a distribution,  click "view" beside it in the distributions view.   
+This includes the following fields:
+- distribution id (for our reference for support) ,
+- Source location  (the storage location the inventory came from),
+- Agency representative ,
+- Delivery method (pickup delivery or shipped),
+- Shipping cost (if shipped),
+- Comments, and
+- the current status.
+  [TODO: add screenhot of view]
+  [TODO:  check -- do we use "state" throughout -- I feel like we probably use "status"]
+## Editing a Distribution
+To edit a distribution,  click on "Edit" beside the distribution in the list,  or on "Make a Correction" in the view.
+
+If the distribution is in the past,  you will see a warning to that effect -- because we assumed that you wouldn't normally need to change the distribution once it had gone out the door!
+We will give you a stern warning if there has been an audit since the distribution was entered, and you may be prevented from changing some distribution information (such as the storage location), because we just don't know how to handle some of those cases.
+[TODO:  More writing about the PACKS version]
+[TODO:  screenshot]
+## Printing a Distribution
+Printing a distribution produces an invoice-like page that can be used as a packing slip.
+
+It is somewhat configurable -- there are options on your [Organization](getting_started_customization.md) page to allow you to: a) add a place for a signature, or b) hide certain columns in the printout.
+[TODO:  point that at the exact location in the document]
+
+Please note that your logo (also configurable on the organization, above) is included on this printout -- we strongly advice keeping it fairly small, as a large logo will just be resized anyway, and will potentially break this function.
+
+## Reclaiming a Distribution
+What do you do if, for some reason, the distribution that was entered was not picked up?   You can reclaim it,  adding the items back into your inventory.
+To do this,  click "Reclaim" beside the distribution in question.
+NOTE:  You can not reverse a reclaim.  If you do it by accident, you will have to re-enter the distribution.
+[Prior: Requests](essentials_requests.md)[Next: Pick Ups and Deliveries](essentials_pick_ups.md)