Documentation improvements
ileben opened this issue · 4 comments
Here are some suggestions to improve the documentation based on my recent experience of upgrading to 1.0 and trying to integrate my custom rules into user directory:
https://caster.readthedocs.io/en/latest/readthedocs/User_Dir/Caster_User_Dir/
- add link from items in the layout description section to https://caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/rules/, https://caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/settings/ etc
https://caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/rules/
- The Whitelist section states that the newly encountered rules are added to the whitelist, but it does not explicitly state whether they get enabled or disabled, so it leaves that undefined. However, I reckon most users would interpret that to mean they get enabled as well, which is not what currently happens. Personally I also think they should get enabled automatically (provided that they load without errors). It means there is less friction to start usage, because the user doesn't need to figure out how to enable it (in contrast everyone intuitively knows how to disable it - at the very least by just deleting the get rule function).
https://caster.readthedocs.io/en/latest/readthedocs/Rule_Construction/Rule_Construction/
- should explicitly mention that it refers to loading the rules from the rules/ subfolder of the user directory
- the introduction of the
get_rulefunction makes it sound like this is an existing function provided by caster: "The get_rule() function returns RuleDetails parameters and the rule class." Instead should explicitly state that the user needs to implement this function in the global scope of every file in the rules folder and clarify that all other files will be ignored. - add an example of a Non-CCR Non-App rule to make it clear that it is valid to construct RuleDetail without executable and without ccrtype arguments
- should include a link to https://caster.readthedocs.io/en/latest/readthedocs/Rule_Construction/Dragonfly_Rules/Sample_File/
- note that the sample file would be more useful if it included the get_rule function to make it caster example
Thank you for this feedback It's invaluable. I'm a bit busy over the next few days but after that I will see if I can get those points clarified.
Just to let you know I am working on this. Expect a PR soon you to review.
progress on https://caster-lexiconcode.readthedocs.io/en/docs/
* he Whitelist section states that the newly encountered rules are added to the whitelist, but it does not explicitly state whether they get enabled or disabled, so it leaves that undefined. However, I reckon most users would interpret that to mean they get enabled as well, which is not what currently happens. Personally I also think they should get enabled automatically (provided that they load without errors). It means there is less friction to start usage, because the user doesn't need to figure out how to enable it (in contrast everyone intuitively knows how to disable it - at the very least by just deleting the get rule function).
https://caster-lexiconcode.readthedocs.io/en/docs/readthedocs/Caster_Settings/rules/
Enabling all grammars by default would not be helpful just possibly application grammars. (many people describe it as a verbal minefield in the past), However I'm not sure how to do this for newly added rules and differentiating when when Castor starts up for the 1st time loading its rules.
Honestly though I think the appropriate solution is to have a GUI show that grammars available and what to say to activate it.
caster.readthedocs.io/en/latest/readthedocs/User_Dir/Caster_User_Dir
* add link from items in the layout description section to [caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/rules](https://caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/rules/), [caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/settings](https://caster.readthedocs.io/en/latest/readthedocs/Caster_Settings/settings/) etc
Done https://caster-lexiconcode.readthedocs.io/en/docs/readthedocs/User_Dir/Caster_User_Dir/
should explicitly mention that it refers to loading the rules from the rules/ subfolder of the user directory
the introduction of the
get_rulefunction makes it sound like this is an existing function provided by caster: "The get_rule() function returns RuleDetails parameters and the rule class." Instead should explicitly state that the user needs to implement this function in the global scope of every file in the rules folder and clarify that all other files will be ignored.add an example of a Non-CCR Non-App rule to make it clear that it is valid to construct RuleDetail without executable and without ccrtype arguments
https://caster-lexiconcode.readthedocs.io/en/docs/readthedocs/Rule_Construction/Loading_Rules/
- should include a link to caster.readthedocs.io/en/latest/readthedocs/Rule_Construction/Dragonfly_Rules/Sample_File
- note that the sample file would be more useful if it included the get_rule function to make it caster example
Instead of including a link directly I've asked the user to create that file within their user directory. It's covered under Your_First_Rule in the documentation. I've structured the examples within the basic examples (possibly the Advanced soon) to work using the same grammar an in Your_First_Rule. All the user has to do is copy and paste then save. That way they can work with the rules without having to worry about enablement.