Update documentation

Fix typos, expand and update FAQ.

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>

HISTORY.rst

@@ -1,4 +1,4 @@
-3.2 (2019-04-XX)
+3.2 (2019-06-13)
 ================
 * Split sources models into separate modules.
 * Add support for subfolder scanning to watchfolders. Closes
@@ -82,7 +82,7 @@
 * Move Tag app HTML widgets to their own module.
 * Move the document index app widgets to the html_widget.py
   module.
-* Update group members view permission. The group edit and 
+* Update group members view permission. The group edit and
   user edit permission are now required.
 * Add keyword arguments to messages uses.
 * Add keyword arguments to the reverse use in views.
@@ -125,13 +125,13 @@
 * Add document state action view test.
 * Remove sidebar menu instance. The secondary menu and the
   previour sidebar menu now perform the same function.
-* Backport source column identifiable and sortable 
+* Backport source column identifiable and sortable
   improvements.
 * Update the way the no-result template is shown.
 * Improve TwoStateWidget to use a template. Make
   it compatible with the SourceColumn.
 * Update SourceColumn to support related attributes.
-* Add support for display for empty values for 
+* Add support for display for empty values for
   source columns.
 * Add support for source column object or attribute
   absolute URLs.
@@ -141,10 +141,10 @@
 * Remove the full name from the user list.
 * Add the first name and last name to the user list.
 * Add file metadata app.
-* Add support for submitting forms by pressing the 
+* Add support for submitting forms by pressing the
   Enter key or by double clicking.
 * Rename form template 'form_class' to 'form_css_classes'.
-* Add support for adding form button aside from the 
+* Add support for adding form button aside from the
   default submit and cancel.
 * Update ChoiceForm to be full height.
 * Add AddRemoveView to replace AssignRemoveView
@@ -177,7 +177,7 @@
 * Monkeypatch group and user models to make their fields
   translatable.
 * Add new and default Tesseract OCR backend to avoid
-  Tesseract bug 1670 
+  Tesseract bug 1670
   (https://github.com/tesseract-ocr/tesseract/issues/1670)
 * Load only one language in the document properties form.
 * Convert title calculation form to a template tag.
@@ -231,7 +231,7 @@
   from the document type side.
 * Make workflows, workflows states, workflow
   transitions column sortable.
-* Show completion and intial state in the 
+* Show completion and intial state in the
   workflow proxy instance menu list.
 * Fix translation of the source upload forms
   using dropzone.js
@@ -240,12 +240,12 @@
 * Remove MultipleInstanceActionMixin.
 * Backport MultipleObjectMixin improvements.
 * Remove ObjectListPermissionFilterMixin.
-* Add deprecation warning to convertdb 
+* Add deprecation warning to convertdb
 * Add the preparestatic command.
 * Remove the related attribute of check_access.
 * Remove filter_by_access. Replaced by restrict_queryset.
 * Move the user set password views to the authentication app.
-* All views redirect to common's home view instead of the 
+* All views redirect to common's home view instead of the
   REDIRECT_URL setting.
 * Update tag document list and the document tag list
   views to require the view permissions for both objects.
@@ -264,7 +264,7 @@
 * Add cabinet created and edited events.
 * Show a null mailer backend if there is backend with an
   invalid path. Due to the app full path change, existing
-  mailer setups need to be recreated. 
+  mailer setups need to be recreated.
 * The document link URL when mailed is now composed of the
   COMMON_PROJECT_URL + document URL instead of the Site
   domain.

docs/chapters/deploying.rst

@@ -12,7 +12,7 @@ does.
 
 Compilers and development libraries will be installed to compile runtime
 libraries. LibreOffice and Poppler utils will also be installed as they are
-used to convert document files. Supervisor (http://supervisord.org/), a
+used to convert document files. Supervisor (https://supervisord.org/), a
 Process Control System, will be used to monitor and keep all Mayan processes
 running.
 
@@ -43,7 +43,7 @@ For another setup that offers more performance and scalability refer to the
 
 2. Create the user account for the installation:
 ------------------------------------------------
-   This will create an unpriviledge user account that is also unable to login.
+   This will create an unprivileged user account that is also unable to login.
    ::
 
        sudo adduser mayan --disabled-password --disabled-login --no-create-home --gecos ""
@@ -61,7 +61,7 @@ For another setup that offers more performance and scalability refer to the
 4. Create the Python virtual environment:
 -----------------------------------------
    This will keep all the Python packages installed here isolated from the rest
-   of the Pythoon packages in the system.
+   of the Python packages in the system.
    ::
 
        sudo virtualenv /opt/mayan-edms
@@ -113,9 +113,9 @@ For another setup that offers more performance and scalability refer to the
 
        For simplicity, the ``MAYAN_MEDIA_ROOT`` folder is set to be a subfolder
        of the installation. If you want to keep your files separated from
-       the installation files, change the value of the ``MAYAN_MEDIR_ROOT``
+       the installation files, change the value of the ``MAYAN_MEDIA_ROOT``
        variable in this and all subsequent steps. Be sure to first create the
-       folder and give owership of it to the ``mayan`` user with the ``chown``
+       folder and give ownership of it to the ``mayan`` user with the ``chown``
        command.
 
    .. warning::
@@ -157,7 +157,7 @@ For another setup that offers more performance and scalability refer to the
 
 12. Configure Redis:
 --------------------
-    Configure Redit to discard data when it runs out of memory, not save its
+    Configure Redis to discard data when it runs out of memory, not save its
     database and only keep 1 database:
     ::
 

docs/chapters/docker.rst

@@ -297,7 +297,7 @@ The command line would look like this::
 Now create a watch folder in Mayan EDMS using the path ``/scanned_files``
 and the documents from the host folder ``/opt/scanned_files`` will be
 automatically available. Use the same procedure to mount host folders to be
-used as staging folderes. In this example ``/scanned_files`` was used as the
+used as staging folders. In this example ``/scanned_files`` was used as the
 container directory, but any path can be used as long as:
 
 - the path not an already existing path
@@ -379,7 +379,7 @@ Execute Docker's build command using the provided makefile::
 
     make docker-build
 
-Or using an apt cacher to speed up the build::
+Or using an APT cache to speed up the build::
 
     make docker-build-with-proxy APT_PROXY=172.17.0.1:3142
 

docs/chapters/index_examples.rst

@@ -111,8 +111,8 @@ Index documents not found in any cabinet
     {% if document.cabinets.count == 0 %}No Cabinets{% endif %}
 
 
-Index untagged documents
+Index documents not tagged
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 ::
 
     {% if document.tags.count == 0 %}No Tags{% endif %}

docs/chapters/sources.rst

@@ -74,6 +74,6 @@ Creating new sources
 
 #. Go to the :menuselection:`System --> Setup --> Sources` menu.
 #. From the :guilabel:`Actions` dropdown select the new type of source to create.
-#. Each source type will have different fields to customize its behaviour. Enter
+#. Each source type will have different fields to customize its behavior. Enter
    the required information in each field based on the help text provided.
 #. Press :guilabel:`Save`.

docs/chapters/versioning.rst

@@ -76,5 +76,5 @@ Uploading a new document version
 #. From the :guilabel:`Actions` dropdown select :guilabel:`Upload new version`.
 #. Optionally type a comment explaining the changes in the new version.
 #. Press the :guilabel:`Browse` button and select a new file.
-#. Press :guilabel:`Save` upload the new verision.
+#. Press :guilabel:`Save` upload the new version.
 

docs/mercs/0005-explicit-arguments.rst

@@ -26,7 +26,7 @@ Motivation
 ==========
 
 As the project grows, legibility of code becomes more important. Keyword
-argument help document the use of services, clases and functions. Refactors
+argument help document the use of services, classes and functions. Refactors
 that affect the interface of services are also easier to find and update and
 fix. Positional argument can cause a call to continue working as long as the
 datatype of the argument remains the same. Usage of keyword arguments will
@@ -121,7 +121,7 @@ After:
 Keyword arguments should also be used for callables that pass those to others
 down the line like Django's ``reverse`` function. Any change to the name of
 the ``pk`` URL parameter will raise an exception in this code alerting to
-any posible incompatible use.
+any possible incompatible use.
 
 
 Example:
@@ -138,7 +138,7 @@ This becomes even more important when multiple URL parameters are used. Since
 the API documentation is auto generated from the code itself, it would make
 sense to rename the first URL parameter from ``pk`` to ``document_pk``. Such
 change will cause all address to view resolutions to break forcing their
-update and allowing all consumers' interface usage to remain synchonized to the
+update and allowing all consumers' interface usage to remain synchronized to the
 callable's interface.
 
 .. code-block:: python

docs/mercs/0006-lower-information-disclose.rst

@@ -16,7 +16,7 @@ MERC 6: Lower information disclose
 Abstract
 ========
 
-This MERC proposes the use of errors that don't disclose the existance of a
+This MERC proposes the use of errors that don't disclose the existence of a
 resource in the event that the requester doesn't have the required credentials.
 
 Motivation
@@ -43,7 +43,7 @@ Since most view use the internal custom CRUD classes making a change to the
 failure will fulfill the proposal of this MERC.
 
 Adding the ``object_permission_raise_404`` class attribute and setting it
-to default to False will allow fulfullin the goal of this MERC while
+to default to False will allow fulfilling the goal of this MERC while
 keeping the existing functionality intact.
 
 

docs/releases/0.11.rst

@@ -17,11 +17,11 @@ Version 0.11
 * Added a view to delete the document image cache, useful when switching
   converter backends or doing diagnostics.
 * Added South to the requirements.
-* Merged documents' filename and extension database fiels into a single
+* Merged documents' filename and extension database fields into a single
   filename field, filename are store as uploaded not manipulation is done
-  Users with existing data must install South and run the appropiate
+  Users with existing data must install South and run the appropriate
   migrate commands::
-  
+
     $ pip install -r requirements/production.txt
     $ ./manager syncdb
     $ ./manage.py migrate documents 0001 --fake
@@ -30,5 +30,5 @@ Version 0.11
 * Added new office document mimetype
   * application/vnd.ms-office
 * Fixed documents not saving the file encoding
-* Removed extra slash in ajax-loader.gif URL fixes #15, thanks to 
+* Removed extra slash in ajax-loader.gif URL fixes #15, thanks to
   IHLeanne for finding this one

docs/releases/3.2.rst

@@ -1,7 +1,7 @@
 Version 3.2
 ===========
 
-Released: May XX, 2019
+Released: June 13, 2019
 
 Work on version 4.0 continues along. Version 4.0 brings so many changes that it
 missed its release schedule. Therefore we decided to release an interim version,
@@ -67,7 +67,7 @@ Apps
 
 Dependencies app: A new app was added to handle all dependencies. Previously,
 the code to handle JavaScript dependencies and license text collection, was
-contianed in the common app. This new app, called "dependencies" now handles
+contained in the common app. This new app, called "dependencies" now handles
 both tasks. In addition, it provides checks for binary dependencies.
 This app's main view will allow users to know which dependencies are not being
 recognized and help debug installation issues faster and easier. The app
@@ -163,8 +163,8 @@ currently logged user.
 Incompatible changes
 ^^^^^^^^^^^^^^^^^^^^
 
-Existing config.yml files need to be updated manually and 'mayan.apps'
+Existing config.yml files need to be updated manually. The prefix 'mayan.apps'
-prepended to any reference to an app.
+must be added to any reference of an app.
 
 All the Internet Explorer specific HTML markup was removed from the templates.
 
@@ -237,7 +237,7 @@ at the time was to rename Mayan's to "mayan_statistics". With this change
 solutions like this won't be necessary.
 
 This means that any reference to an app, either in the code or from a
-configuration file must now be prepended with ``mayan.apps``. Existing
+configuration file must now be prefixed with ``mayan.apps``. Existing
 ``config.yml`` files need to be updated manually.
 
 For developers, a new test mixin was added called ``SilenceLoggerTestCaseMixin``.
@@ -387,7 +387,7 @@ An optimization was added which removed the exception catch for the
 ``permissions`` argument of the ``check_access`` method. ``permissions``
 argument must now be an iterable.
 
-Signal handlers must now be prepended with ``handler``.
+Signal handlers must now be prefixed with ``handler``.
 
 Remove ``.filter_by_access``. Replaced by ``.restrict_queryset``.
 
@@ -703,13 +703,13 @@ Other changes
 - Add cabinet created and edited events.
 - Chart updates: Show last update date and time in list view and details view.
   Change color scheme to match rest of project. Increase size of data points.
-  Improve responsive settings. Redirect to the current view after queueing.
+  Improve responsive settings. Redirect to the current view after queuing.
 - Split document type retention policies into it own view.
 - Place deletion policies units before periods for clarity.
 - Remove the included Lato font. The font is now downloaded
   at install time.
 - Add support for Google Fonts dependencies.
-- Add support for patchin dependency files using rewriting rules.
+- Add support for patching dependency files using rewriting rules.
 - Allow searching documents by UUID.
 - Improve search negation logic. Only dashes at the start of terms and
   outside of quotes are now interpreted as negation.
@@ -817,33 +817,33 @@ Backward incompatible changes
 - Paths to apps must be updated in existing ``config.yml`` files. Preprend
   ``mayan.apps.`` to any app reference. Some instances:
 
-  .. code-block::
+  .. code-block :: python
 
     LOCK_MANAGER_BACKEND: lock_manager.backends.file_lock.FileLock
 
   to
 
-  .. code-block::
+  .. code-block :: python
 
     LOCK_MANAGER_BACKEND: mayan.apps.lock_manager.backends.file_lock.FileLock
 
-  .. code-block::
+  .. code-block :: python
 
     OCR_BACKEND: ocr.backends.pyocr.PyOCR
 
   to
 
-  .. code-block::
+  .. code-block :: python
 
     OCR_BACKEND: mayan.apps.ocr.backends.pyocr.PyOCR
 
-  .. code-block::
+  .. code-block :: python
 
     CONVERTER_GRAPHICS_BACKEND: converter.backends.python.Python
 
   to
 
-  .. code-block::
+  .. code-block :: python
 
     CONVERTER_GRAPHICS_BACKEND: mayan.apps.converter.backends.python.Python
 
@@ -854,7 +854,7 @@ Backward incompatible changes
 
 - To collect and compress the static media files, use the new ``preparestatic``
   command instead of the traditional ``collectstatic``. Both work the same
-  way, but ``preparestatic`` has a default backlist to avoid collecting
+  way, but ``preparestatic`` has a default blacklist to avoid collecting
   test files.
 
 - Instead of the ``collectstatic``, the new ``preparestatic`` command should be

docs/spelling_wordlist.txt

@@ -143,6 +143,7 @@ storages
 Storages
 subclasses
 subclassing
+subfolder
 sublicense
 sublicensees
 swedish

docs/topics/faq.rst

@@ -6,6 +6,88 @@ FAQ
 Non technical
 *************
 
+Contact
+=======
+
+Can I contact members of the development team?
+----------------------------------------------
+
+Direct access to members of the development team is reserved for clients
+of a support or consultation contract.
+
+
+I can't pay for support/consultation
+------------------------------------
+
+A community forum is available at https://forum.mayan-edms.com. Members of
+the development team visit the forum on occasions and might answer some
+questions on a voluntary basis.
+
+
+I found a bug
+-------------
+
+For bugs, open an issue at https://gitlab.com/mayan-edms/mayan-edms/issues.
+
+
+I found a security issue
+------------------------
+
+Open an issue at https://gitlab.com/mayan-edms/mayan-edms/issues and mark it as
+Confidential. Allow us at least 48 hours to find and release a fix
+for the issue before submitting it to the CVE database.
+
+
+I want to join the development team
+-----------------------------------
+
+Perfect! We need all the help we can get. Tell us where we can see what you've
+done using Mayan EDMS. It could be a fork, a new UI, an API client, a custom app,
+or anything else that you think will be able to evidence your dominion over the
+codebase.
+
+
+I submitted an issue and it has not been fixed
+----------------------------------------------
+
+There are many reason an issue might not get resolved and remain open for an
+extended period of time. We document on the issue itself the progress and when
+resolved will reference what commit fixed it and the version or approximate time
+for the code to make it into a production release. Some reason why issues remain
+open with no resolution are:
+
+- It was not an issue with the code. It happens that sometimes the problem lies
+  with the operating system, the filesystem being used, the platform or packaging
+  method.
+- It was not an issue but a question or a comment. The issue system is for reporting
+  problems with the code. That said, we sometimes answer questions submitted as
+  issues. For questions or discussions use the community forum.
+- We are not able to reproduce the issue. We need to be able to recreate the
+  conditions that trigger the issue so that we can pinpoint the cause. After that
+  we create a test to make sure the issue is really fixed. Some issues can
+  be triggered manually easily but are hard to trigger programatically.
+- The issue is not clearly explained. Issue descriptions like: "It doesn't work",
+  or "It showed an error but I forgot to write it down" are almost impossible to
+  resolve.
+- We understand the cause of the problem but don't yet a solution to implement.
+  We have studied the issue and have been able to reproduce it, but have not
+  reached a consensus on how it should be fixed. Could be that the solution is
+  beyond the collective expertise of the development team or that a design
+  decision of big impact is needed before code changes can be implemented.
+- The issue is no real. The issue might be for an obsolete version. It could be
+  for a fork or a program that is not developed by us. Sometimes they are just
+  fake issues.
+
+
+I submitted a merge request and has not been merged
+---------------------------------------------------
+
+Merge requests must follow the development standards of the code as close a
+possible. They must also be atomic and as small as possible. The code must also
+not change the behavior of the project. We can't accept merge request that
+customize it in some way based on your own preferences or needs.
+
+
 Distribution
 ============
 
@@ -44,6 +126,7 @@ Restricting distribution or sale would conflict with the license terms. This
 would possible for a commercial version of Mayan EDMS with separate licensing
 terms.
 
+
 Is there a commercial partnership program?
 ------------------------------------------
 
@@ -84,17 +167,6 @@ upgrades, if a migration fails the database structure is left in a transitory
 state and has to be reverted manually before trying again.
 
 
-Document versions
-=================
-
-How do you upload a new version of an existing file?
-----------------------------------------------------
-
-Choose a document, and go to the versions tab, on the right menu at the bottom
-under Other available action there is Upload new version. Clicking it will
-take you to a very similar view as the Upload new document but you will be
-able to specify version number and comments for the new version being uploaded.
-
 LDAP
 ====
 
@@ -105,6 +177,7 @@ A sample settings file called ldap_connection_settings.py is included in the
 contrib/settings/ folder of the repository showing how to setup LDAP
 authentication.
 
+
 Operating systems
 =================
 
@@ -154,14 +227,18 @@ should be used and the resulting static folder served from a webserver.
 For more information check the
 :django-docs:`howto/static-files/`
 
-Watchfolders
+
-============
+Watch folders
+=============
 
 The watched folder feature is not working
 -----------------------------------------
 
 Make sure that the Celery BEAT scheduler is running correctly as it is the
-element that triggers the periodics tasks.
+element that triggers the periodic tasks. Check that the user running the Mayan
+EDMS services has read and write permissions for the watch folder.
+
+
 
 Other
 =====
@@ -188,8 +265,3 @@ Example::
 
 Reference:
 * http://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html
-
-Can you change the display order of documents…i.e can they be in alphabetical order?
-------------------------------------------------------------------------------------
-
-A the moment no, but it is something being worked on.