Docs - Improve user guidance

[stufraser1]

Improvements to make:

• [ ] include practical examples of how to use when clauses, to assist users clearly (feedback shows users don't know what is possible yet). Some of this is documented under 'further information on mapping files' page
• [ ] information on how the conversion file should be built up. How the definition files should be defined. (Supports the need for file building wizard and validator). Some of this is documented under 'Inputs'
• [ ] Add in a section on error handling - format of error messages (i.e., what it says), where they are logged, and what the error log looks like. To be completed when error handling functions are improved.
• [ ] Change RTD theme colour from blue to IDF red

Completed:

• [x] improve guidance on executing the .exe - specifically advise to UNZIP the file before installing.
• [x] Effect of quoting - what does minimal, full, etc, mean.
• [x] More information on Pandas versus Dasq versus Modin - why, what impact. Guidance on which to use in which cases.
• [x] Mapping file structure - what each piece does. Example of postcode used to justify defining data type - if subset of the data is scanned and understood as char, then there are number-only postcodes, they may not get picked up. and Null value is required, in order to turn blank values in float field, into null. It is universal - applies in same way to all fields. Could be defined / changed to be field specific - Ben to recap/specify example. Also include guidance on mapping file naming - see #6
• [x] Ordering of the mapping file: order of fields does matter in Touchstone files - not critical but would help in manual validation to see fields in order. >> Default mapping files should have correct order of fields. see #5
• [x] AIR contract row-wise data is OK, but tool doesn't combine data, so column-wise wouldn't be
• [x] How does the tool find mapping files. (running cmd locally, will look for converter/data/mappings; running exe via UI, increasing number of default files will be packaged with the exe.)
• [x] #71
• [x] IDF branding (logo)
• [x] Adjust name and URL to reflect OED transformation not OASIS convertor
• [x] Add more general introduction
• [x] Revise TOC to put developer contents in one section
• [x] add user guide step by step
• [x] reference licence statement
• [x] explain not including filepaths - all data stored in same folder doesn't need full path in config file
• [x] explain reference to mapping file (doesn't have to be in the same folder - code will look in ...)
• [x] mapping file - explain that the types refer to the source data format.
• [x] mapping file - highlight the input and output format, make the link to the config file (already made the other way)

[stufraser1]

Address feedback received on execution: Based on .docx documentation file, insufficient supporting documentation supplied at this step: "A pair of configuration files should be provided. The transformation configuration file is a .yml file. It defines the names of the input files and the mapping files to run. It contents are as follows. The runner can be left as ‘converter.runner.PandasRunner’ – multiple runners are available but for small portfolios there is little difference in performance. See documentation for more on this." This may refer to the final sentence (needs link to documentation - or ensure online doc provides all the necessary info and examples)

"A mapping file for each of the location and account files should be provided. Their header should contain the model version, mapping version, and creator information:" The instructions are more about the configuration Mapping file rather than the process of the conversion itself. >> Improve clarity in documentation between configuration and execution.

It is unclear where to provide the path and name of the file in the instructions. >> This needs to be made absolutely clear.

[stufraser1]

Address feedback received on installation - Feedback received from industry cat analysts:

A lack of instruction in the documentation on installation of Python and [use of] Github. People with no background of Python can find it difficult to get understand the instructions to install the package in the first place, since there is no user interface.

Installation by non-expert in Python resulting in error "Invalid requirement 'git+'"

@OmegaDroid, @benhayes21 How best to make sure non Python users don't get tripped up at this stage?

Is it feasible to include in the documentation common reasons why the error Invalid requirement 'git+' might be triggered? Clearly we can't be exhaustive, but can we give a clue of what to look for and change, before directing users to leave an issue / request for help here? Potentially

White space in the user-defined path
Local Python version is not Python 3.8+
more?

[stufraser1]

Main to-do list edited with feedback from participants of ODTF Ops Workshop (30 Mar 2022):

• information on how the conversion file should be built up. How the definition files should be defined. (Supports need for file building wizard and validator).
• Effect of quoting - what does minimal, full, etc, mean.
• More information on Pandas versus Dasq versus Modin - why, what impact. Guidance on which to use in which cases.
• Mapping file structure - what each piece does. Example of postcode used to justify defining data type - if subset of the data is scanned and understood as char, then there are number-only postcodes, they may not get picked up. and Null value is required, in order to turn blank values in float field, into null. It is universal - applies in same way to all fields. Could be defined / changed to be field specific - Ben to recap/specify example.
• How does it find mapping files. - Ben answer - running cmd locally, will look for converter/data/mappings; running exe via UI, increasing number of default files will be packaged with the exe.
• Ordering of the mapping file: order of fields does matter in Touchstone files - not critical but would help in manual validation to see fields in order. >> Default mapping files should have correct order of fields.
• AIR contract row-wise data is OK, but tool doesn't combine data, so column-wise wouldn't be

[stufraser1]

Updates to the documentation should also follow addition of error handling and other major updates