Merge #6395

6395: Update online documents r=jniles a=jmcameron

Updated stock management documents.

After this is merged, these documents will be available at:  https://docs.bhi.ma/en/stock-management/

The purpose of this update is to prepare for future projects that plan to use BHIMA but require updated documentation.

Most of this material is based on a Stock Management document produced by A.G. Neron in French.

NOTE: This is only for the English documentation.  No French documents were updated.


-----
[View rendered docs/en/stock-management/accounting/ohada.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/accounting/ohada.md)
[View rendered docs/en/stock-management/depot.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/depot.md)
[View rendered docs/en/stock-management/glossary.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/glossary.md)
[View rendered docs/en/stock-management/index.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/index.md)
[View rendered docs/en/stock-management/inventory.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/inventory.md)
[View rendered docs/en/stock-management/movement.adjustment.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/movement.adjustment.md)
[View rendered docs/en/stock-management/movement.entry.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/movement.entry.md)
[View rendered docs/en/stock-management/movement.exit.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/movement.exit.md)
[View rendered docs/en/stock-management/overview.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/overview.md)
[View rendered docs/en/stock-management/stock.settings.md](https://github.com/jmcameron/bhima/blob/update-stock-management-docs/docs/en/stock-management/stock.settings.md)

Co-authored-by: Jonathan Cameron <jmcameron@gmail.com>

docs/en/stock-management/accounting/ohada.md

@@ -2,6 +2,5 @@
 
 # OHADA Accounting for Stock Management
 
-Seventeen states in western and central Africa subscribe to the [Organization for the Harmonization of Business Law in Africa (OHADA)](https://www.ohada.org/en/general-overview/) 
-standard for accounting and business law.  
+Seventeen states in western and central Africa subscribe to the [Organization for the Harmonization of Business Law in Africa (OHADA)](https://www.ohada.org/en/general-overview/) standard for accounting and business law.  
 

docs/en/stock-management/average-monthly-consumption.md

@@ -0,0 +1,31 @@
+» [Home](../index.md) / [Stock Management](./index.md) / Average Monthly Consumption
+
+# Average Monthly Consumption by Depot
+The Average Monthly Consumption (AMC) is calculated for the enterprise as a
+whole and for individual depots.  The calculation is slightly different
+though, depending on the type of depot.
+
+For dispensing pharmacies, the Average Monthly Consumption is calculated based
+on the distributions/exits to _patients_ or _services_.  These are considered
+consumption of the depot and factor into the average monthly consumption.
+
+For warehouses, BHIMA considers transfers to other depots as consumption in
+addition to the exits to patients and services.  By including transfers, BHIMA
+can estimate when to refill stock in warehouses when they otherwise would not
+be considered.
+
+BHIMA offers two choices of algorithm that differ slighty:
+
+  1. **Default Algorithm** - The average monthly consumption is obtained by
+  dividing the quantity consumed during the period by the number of days with
+  stock during the period, and by multiplying the result by 30.5.
+
+  2. **MSH Algorithm** - The average consumption is obtained by dividing the
+  quantity consumed during the period by number of months of stock (found by
+  subtracting the number of days of stock outs divided by 30.5 from the number
+  of months in the period).  The MSH algorithm is recommended by the
+  [Management Sciences for Health](https://www.msh.org) organization.
+
+These algorithms produce identical or similar results.  The main difference is
+in rounding - the MSH algorithm converts to months before the computation
+while the default algorithm converts to months as a last step.

docs/en/stock-management/depot.md

@@ -12,46 +12,77 @@
   </p>
 </div>
 
-
-Depots are used to store articles.  We can not talk about stock without talking about depots. The depot forms
-a container for the enterprise's stock, and allows users to enter stock through [Stock Entry](./movement.entry.md), or dispense
+Depots are used to store stock articles.  We cannot discuss stock without
+talking about depots since all stock articles are assigned to specific
+depots. The depot forms a container for the enterprise's stock, and allows
+users to enter stock through [Stock Entry](./movement.entry.md), or dispense
 stock through [Stock Exit](./movement.exit.md).
 
-To create a new depot, click on the **Add Depot** button in the top right corner of the module.  This opens a
-modal window to enter the depot information.
-
+To see the registry of depots:
 
-## Depot Heirarchies
-BHIMA allows users to structure their depots in a tree hierachary of parents and children, similar to the chart
-of accounts.  This feature exists to allow easier permissions management.  If a user is responsible for many depots
-in a region, it may make sense to group these regionally and assign a user the permissions to all child depots in that
-region.  Functionally, the parent-child relationship has no bearing on which depots can transfer stock between one another.
+<div class="bs-callout bs-callout-success">
+  <p>
+  <i>menu</i> > Stock > <strong>Depot Management</strong> <br>
+   &rArr; Opens a registry of known depots and allows editing existing depots and creating new ones
+  </p>
+</div>
 
+To edit an existing depot, click on the **Action** link on the right end of
+the row of the depot to edit.  Then click on the "Edit" link, make the changes
+on to the depot and then click the **[Submit]** button on the bottom of the
+edit form.
 
-## Depot Capabilities
-Each depot can be customized to allow only certain kinds of entries and exits.  For example, a central
-warehouse might not distribute directly to patients, but may serve as a staging center to distribute to
-other depots.  Similarly, a depot could be a distribution center only and not allow direct entry of
-donated or purchased stock.
+To create a new depot, click on the **[Add Depot]** button in the top right
+corner of the page.  This opens a modal window to enter the depot information.
+While creating a new depot, you will need to specify the supplier.  For more
+details on creating and editing suppliers within BHIMA, please see the
+[Supplier documentation](./supplier.md).
 
 
-## Average Monthly Consumption by Depot
-The Average Monthly Consumption (AMC) is calculated for the enterprise as a whole and for individual depots.  The
-calculation is slightly different though, depending on the type of depot.
+## Depot Heirarchies
+BHIMA allows sites to structure their depots in a tree hierachary of parents
+and children, similar to the chart of accounts.  This feature exists to allow
+easier permissions management.  If a user is responsible for many depots in a
+region, it may make sense to group these regionally and assign a user the
+permissions to all child depots in that region.  Functionally, the
+parent-child relationship has no bearing on which depots can transfer stock
+between one another.
 
-For dispensing pharmacies, the Average Monthly Consumption is calculated based on the distributions/exits to _patients_
-or _services_.  These are considered consumption of the depot and factor into the average monthly consumption.
 
-For warehouses, BHIMA considers transfers to other depots as consumption in addition to the exits to patients and services.
-By including transfers, BHIMA can estimate when to refill stock in warehouses when they otherwise would not be considered.
+## Depot Capabilities
+Each depot can be customized to allow only certain kinds of entries and exits.
+For example, a central warehouse might not distribute directly to patients,
+but may serve as a staging center to distribute to other depots.  Similarly, a
+depot could be a distribution center only and not allow direct entry of
+donated or purchased stock.
 
-BHIMA offers two choices of algorithm that differ slighty:
+## Getting Access to a Depot
+Before managing or accessing a depot, a user have authorization. To get
+access, open the User Management page:
 
-  1. **Default Algorithm** - The average monthly consumption is obtained by dividing the quantity consumed during the period by
-  the number of days with stock during the period, and by multiplying the result by 30.5.
-  2. **MSH Algorithm** - The average consumption is obtained by dividing the quantity consumed during the period by number of
-  months of stock (found by subtracting the number of days of stock outs divided by 30.5 from the number of months in the period).
-  The MSH algorithm is recommended by the [Management Sciences for Health](https://www.msh.org) organization.
+<div class="bs-callout bs-callout-success">
+  <p>
+  <i>menu</i> > Administration > <strong>User Management</strong> <br>
+   &rArr; Opens a registry of users
+  </p>
+</div>
 
-These algorithms produce identical or similar results.  The main difference is in rounding - the MSH algorithm converts to months
-before the computation while the default algorithm converts to months as a last step.
+Use the **Action** link on the right end of the line for the user you wish to
+update and click on the "Depot Management" menu item.  A form will appear that
+will allow you to enter the name of the depot you want to obtain permission to
+manage. Click in the input box under the "Add:" and begin typing the depot
+name. After you type in a few characters, BHIMA will look up the depot by name
+and the full name should appear. Click on it to select it. The depot name
+should now be shown.
+
+If you do not see any depots names loaded, this could mean that either you
+have a slow connection to the server or your have mistyped your depot
+name. Confirm the name is of an existing depot and try again.
+
+Then confirm the authorization by clicking on the blue **[Submit]** button.
+If the operation is successful, a green "Updated" message will appear briefly
+at the top of the page.
+
+Enabling this authorization is only necessary once (per user). Once done, the
+user will be able to carry out operations related to stock movements with the
+authorized depot.

docs/en/stock-management/glossary.md

@@ -0,0 +1,82 @@
+# GLOSSARY
+
+  - **DEPOT** - A "depot" is a location where significant numbers of stock items
+    are stored until they are needed.  The size and function of a Depot can
+    vary from a large storehouse for handling transfers of drugs to a small
+    pharmacy in a clinic for dispensing drugs to patients.
+
+  - **PHARMACY** - A location used to store and provide medications (and other
+    related stock items) as needed by Patients, Services, or other Pharmacies.
+
+     - Stock Pharmacy - A Stock Pharmacy is typically a local storage facility
+       that receives stock from depots and suppliers and provides stock to
+       other pharmacies.  A stock pharmacy does not generally dispense
+       medications directly to patients.
+
+     - Dispensing Pharmacy - A Dispensing Pharmacy (Pharmacie D'Usage in
+       French) is a pharmacy that dispenses stock to patients, wards, and
+       services.  Normally, stock is not transferred from Dispensing
+       Pharmacies to other Pharmacies.
+
+  - **LOT** - A "Lot" is a collection of identical stock items that are usually
+    purchased and tracked together.  For instance, a box of pills
+    might be part of a lot of that type of medication.  But "Lot" is also a
+    more general term.  For instance, a single piece of equipment may be
+    purchased by itself but for stock tracking purposes, it would be
+    considered to be in a lot of 1 stock item.
+
+  - **SERVICE** - In the BHIMA perspective, a "Service" is a department in the
+    hospital such as "pediatrics", "ophthalmology", "internal medicine",
+    "pharmacy", or "administration".  Services can be assigned invoices,
+    consume medications, contain staff, and have both profit and loss centers.
+
+  - **STOCK** - "Stock" are any items used in the operation of a hospital or
+    clinic.  Examples include drugs for treating patients, medical equipment
+    and supplies, and administrative supplies.  "Stock" items are often
+    purchased in "Lots" which include a number (or identifier) of the stock
+    items.  Where possible BHIMA uses the lot number provided by the
+    manufacturer (see this [Wikipedia article](https://en.wikipedia.org/wiki/Lot_number) 
+    for more information).
+
+  - **STOCK ADJUSTMENT** - When a physical inventory of stock reveals that the
+    actual count of stock items differs from the count in the "Theoretical
+    Quantity" (as tracked by the BHIMA system), then an "Stock Adjustment"
+    should be performed to update the BHIMA system (and the "Theoretical
+    Quantity".
+
+  - **STOCK ENTRY** - "Stock entries" occur when an item of stock is added to a
+    Depot.  Types of stock entries include:
+
+     - **Purchase** - stock items entering the Depot from a fulfilled purchase
+       order
+
+     - **Donation** - stock items entering the Depot from a donation
+
+     - **Integration** - stock items entering the Depot that do not have a known
+       origin but are necessary to be tracked in the system.  This often
+       happens during start-up - stock is found on the shelf, but it isn't
+       necessarily clear where it came from.  It's easiest to simply
+       "integrate" the stock as-is, rather than try to reproduce the history
+       exactly from previous documentation.
+
+     - **Transfer** - stock items entering the Depot due to a transfer from some other Depot.
+
+  - **STOCK EXIT** - "Stock exits" occur when an item is removed from a Depot.
+    This includes exits due to:
+
+     - **Exit to an individual** - Stock items leaving the depot for use in the
+       hospital or clinic
+
+     - **Distribution to a service** - Stock items leaving the depot for use by a
+       hospital service (such as sutures for the operating room).
+
+     - **Distribution to a depot** - Stock items leaving the depot to be
+       transferred to another depot.
+
+     - **Loss** - Stock items that are declared lost or expired and removed from
+       the inventory of stock items.  This may happen when a direct review of
+       the stock items reveals that some items are missing or expired.
+
+  - **SUPPLIER** - A supplier is the source of the stock items coming into depots
+    from purchases.  They are represented as a creditor in the accounting
+    module.

docs/en/stock-management/index.md

@@ -6,25 +6,38 @@ Inventory and stock management modules provide a robust stock management solutio
 hospitals.  Below you'll find an index to particular subsections that may be of interest.
 
 1. [Overview](./overview.md)
+
 2. [Inventories](./inventory.md)
+
 3. [Depots](./depot.md)
-4. [Stock Settings](./stock.settings.md)
-5. [Stock Accounting](./accounting/index.md)
+
+4. [Suppliers](./supplier.md)
+
+5. [Stock Settings](./stock.settings.md)
+
+6. [Stock Accounting](./accounting/index.md)
     1. [OHADA Accounting](./accounting/ohada.md)
     2. [IFRS Accounting](./accounting/ifrs.md)
-6. [Stocks Movements](./movement.md)
+
+7. [Stocks Movements](./movement.md)
     1. [Stocks Entries](./movement.entry.md)
     2. [Stocks Exits](./movement.exit.md)
     3. [Adjustments](./movement.adjustment.md)
-7. [Inventory Reports]()
+    4. [Average Monthly Consumption](./average-monthly-consumption.md)
+
+8. [Inventory Reports]()
     1. [Stocks]()
     2. [Inventory Status]()
     3. [Inventory Value]()
-8. [Inventory Records]()
+
+9. [Inventory Records]()
     1. [Lots Registry]()
     2. [Articles in Stock Registry]()
     3. [Movement Log]()
-9. [Additional Tools]()
+
+10. [Additional Tools]()
     1. [Import Stock from a CSV File]()
     2. [Assignment of Lots]()
     2. [Lot Assignment History]()
+
+11. [Glossary of Stock-Related Terms](./glossary.md)

docs/en/stock-management/inventory.md

@@ -6,7 +6,7 @@ In BHIMA, "inventory" refers to information about products or services are sold
 
 The difference between inventory and stock in BHIMA is that inventory is the description of a product (or service), whereas stock is the physical asset stored in the depot.
 
-For example, an inventory item might be a "Appendectomy" which is a service and will not have a representation in stock.  However, the inventory item "Quinine 500mg" will have a representation in stock as pills bought on a given date with a quantity and expiration date.
+For example, an inventory item might be a "Appendectomy" which is a service and will not have a representation in stock.  However, the inventory item "Quinine 500mg" will have a representation in stock as pills bought on a given date with a quantity and expiration date.  Similarly, a computer used in a specific department would be an **asset** that might assigned to someone but still considered to be in a "depot".
 
 There are two modules that compose BHIMA's inventory management:
 
@@ -17,15 +17,16 @@ We'll cover each of these below.
 
 ### Inventory Registry
 
-The Inventory Registry provides an overview of all inventory items in the application.  To access the Inventory Registry module:
+The Inventory Registry provides an overview of all inventory items in the application.  To access the Inventory Registry module, under the main menu, select **Inventory** and then **Inventory Registry**:
 
 <div class="bs-callout bs-callout-success">
   <p>
-    Inventory > <strong>Inventory Registry</strong>: This module is a registry that lists all inventory times in the system, allows you to create new ones, or import an inventory from a CSV file.
+    <i>menu</i> > Inventory > <strong>Inventory Registry</strong> <br>
+     &rArr; Opens a registry that lists all inventory times in the system, allows you to create new ones, or import an inventory from a CSV file.
   </p>
 </div>
 
-The registry also has links inline to the Invoices Registry, Stock Movements Registry, Articles in Stock Registry, and Inventory Changes Report.
+Each line of the inventory registry describes one type of inventory item.  At the end each line is an "Action" menu containing links to the Invoices Registry, Stock Movements Registry, Articles in Stock Registry, and Inventory Changes Report.
 
 
 #### Creating an Inventory Item
@@ -38,6 +39,7 @@ To create a new inventory item, click on the **+ Add Inventory** button which wi
 4. **Group** - the inventory group set in the [configuration](#configuration) section.
 5. **Type** - the type of inventory item. This distinguishes between goods ands services.
 6. **Unit** - the unit of measurement for the inventory item.  This is typically "pills", "tablets", "milligrams", "liters", "boxes" or some other basic unit.
+7. **Is an asset** - For items which are organizational assets (eg, computers, etc)
 
 There are also some optional properties:
 
@@ -50,6 +52,7 @@ There are also some optional properties:
 7. **Purchase Interval** - (?)
 8. **Sellable** - indicates if the item can be sold to clients in the Patient Invoice module. Defaults to `true`.
 9. **Note** - an open text field for notes on the item.
+10. For **assets** there are a few additonal fields related to manufacturer brand and model names.
 
 As mentioned above, the inventory requires some prerequisite information beforehand. These prerequisites must exist in the system before creating the inventory item.
 
@@ -79,7 +82,8 @@ To access the module related to the inventory configuration:
 
 <div class="bs-callout bs-callout-success">
   <p>
-  Inventory > <strong>Configuration</strong>: This module allows you to create, edit, and delete inventory groups, inventory types, and inventory units.
+  <i>menu</i> > Inventory > <strong>Configuration</strong> <br>
+   &rArr; Opens a page that allows you to create, edit, and delete inventory groups, inventory types, and inventory units.
   </p>
 </div>