Simplified documentation for creating your own rules

LexiconCode commented 3 years ago

Description

Simplifies documentation for rule creation by reducing dragonfly references.

Motivation and Context

In the past documentation is referenced both dragonfly and Caster way of creating commands. This is created unneeded complexity for the user experience. This PR archives all related dragonfly documentation related to rule creation.

Please review the documentation in the URL as it represents what is in this PR. https://caster-lexiconcode.readthedocs.io/en/docs/

Types of changes

[x] Docs change / refactoring / dependency upgrade
[ ] Bug fix (non-breaking change which fixes an issue or bug)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
[ ] Renamed existing command phrases (we discourage this without a strong rationale).

Checklist

[ ] I have read the CONTRIBUTING document.
[ ] My code follows the code style of this project.
[ ] I have checked that my code does not duplicate functionality elsewhere in Caster.
[ ] I have checked for and utilized existing command phrases from within Caster (delete if not applicable).
[ ] My code implements all the features I wish to merge in this pull request.
[ ] My change requires a change to the documentation.
[x] I have updated the documentation accordingly.
[ ] I have added tests to cover my changes.
[ ] All new and existing tests pass.

Maintainer/Reviewer Checklist

[ ] Basic functionality has been tested and works as claimed.
[ ] New documentation is clear and complete.
[ ] Code is clear and readable.

esc123 commented 3 years ago

I'm going to go out on a limb and assume that the documentation for Caster should be sufficiently comprehensive for people who are completely new to programming. In that light, useful additions to the rule editing section would include:

A list of knowledge prerequisites in the Python programming language that should be understood before tackling editing grammars written right at the top of the page e.g., Data types (integers, strings), data structures (lists, dictionaries) and functions are absolutely essential to understand I would think. Without this, the programming syntax inherent in the grammars such as colons, commas etc. will be baffling and easily lead to errors/discouragement for a new user and programming novice. A suggested info source would also be of no harm. I rather like Corey Schafers python tutorials on youtube but that's just my preference.
Explaining the rules directory immediately is great. I would add a little further details however in the steps to create a "caster_example_rule.py" for clarity.

Create a new file called caster_example_rule.py (and save it in the rules folder of your caster user directory)
Copy and paste the entire contents of Example Rule Code (found below) into caster_example_rule.py
Simply start/restart Caster (you can say "reboot dragon" if using DPI) for the new rule to be recognized.

In the "Basic Caster Rules" page I would be tempted to include a sentence on what is CCR and nonCCR and the differences between them immediately. It is stated that at the end there is a CCR primer (I couldn't find it) and a lack of a necessary pause is mentioned but I wouldn't think that would be enough to be absolutely clear. Something like

"the beginning of this guide demonstrates how to get started making basic non-CCR rules. CCR stands for "continuous command recognition" and refers to the ability for the user to dictate strings of individual commands without gaps or pauses. Non-CCR commands require a pause between each spoken command whereas CCR commands can be spoken one after the other without pause".

The second paragraph on this page is not complete and ends midsentence. It also instructs the user to continue using caster_example_rule.py but the sample rule below it is a different grammar file. What I suggested thus far is going on the assumption that we are working with what already has been written but this page makes me think that more substantial structural changes are intended.

Anyway, I can continue making suggestions on what is here and work with it or I could give input on how best to restructure it (for the novice programmer as that's where I'm coming from :). Personally, in my opinion the Caster_example_rule.py in the "Your First Rule" page is not ideal as it is syntactically dense and seems more geared towards illustrating what caster can do as opposed to clearly explaining the most basic elements of a rule. For the latter I would suggest a mapping rule containing a single command or maybe two with a spec and an action using Text() then add a command with Key(). BringApp() and Playback() are cool but are hardly ever used and can be described later when the new user is more confident.

Regardless, if you let me know if the plan is to work what is already in the docs or a more complete restructuring is on the cards I will be happy to make further suggestions accordingly.

LexiconCode commented 3 years ago

@esc123 Thank you for that feedback! I will respond more in a couple of days after some night shifts.

esc123 commented 3 years ago

@LexiconCode No problem. Look after yourself, those night shifts are tough!

LexiconCode commented 3 years ago

I'm going to go out on a limb and assume that the documentation for Caster should be sufficiently comprehensive for people who are completely new to programming. In that light, useful additions to the rule editing section would include:

* A list of knowledge prerequisites in the Python programming language that should be understood before tackling editing grammars written right at the top of the page e.g., Data types (integers, strings), data structures (lists, dictionaries) and functions are absolutely essential to understand I would think. Without this, the programming syntax inherent in the grammars such as colons, commas etc. will be baffling and easily lead to errors/discouragement for a new user and programming novice. A suggested info source would also be of no harm. I rather like Corey Schafers python tutorials on youtube but that's just my preference.

* Explaining the rules directory immediately is great. I would add a little further details however in the steps to create a "caster_example_rule.py" for clarity.

1. Create a new file called caster_example_rule.py (and save it in the rules folder of your caster user directory)

2. Copy and paste the entire contents of Example Rule Code (found below) into caster_example_rule.py

3. Simply start/restart Caster (you can say "reboot dragon" if using DPI) for the new rule to be recognized.

I've tried intentionally to keep it very low-key in terms of programming so that it would be more palatable for those without the background. This may be debatable but I have a specific purpose in mind for "caster_example_rule.py".

The purpose of this 1st rule is to explain in plain English without the expectation of a programming background specs and actions in a way that the everyday person can understand. 2nd is the ability for monkey see and monkey do editing which leads to and experience the magic of making an edit to this file and feeling and seeing that they made change happen. 3rd - the knowledge learned through seeing the different types of actions explained in plain English makes it easier to understand later documentation that does become more complex. Hence detailed plain English examples now. It is a valid point that it may be dense but does interfere with the goals of 1 and 2?

If people want to become more advanced they're going to have to learn some programming but I don't want to have to saddle them with the expectation of knowing programming knowledge which is daunting before experimenting with this file. The thought of having programming knowledge is of the biggest barriers to people even try this project.

You bring up a really good point that we should have some resources wanting them to learning Python. However I don't think I can explain Python and the Castor syntax at the same time. To do both of those goals at once would drastically expand the documentation making it even more daunting.

I think a page dedicated to some Python resources would be and some of the concepts that would be helpful to learn. The question is more or less where to introduce that as a resource again not to saddle them with the expectation of knowledge before coming to this particular part of the documentation.

If you were to totally restructure the documentation what would it look like in the table of contents?

esc123 commented 3 years ago

"If people want to become more advanced they're going to have to learn some programming but I don't want to have to saddle them with the expectation of knowing programming knowledge which is daunting before experimenting with this file. The thought of having programming knowledge is of the biggest barriers to people even try this project."

Yeah, I completely understand and pretty much agree. In essence you aim to not scare away non-programmers from caster by giving them a list of items relating to Python that the need to know first before they can commence using Caster.

By suggesting a list of programming knowledge prerequisites, I was doing so with the same intent thinking that it would avoid scaring off non-programmers by avoiding any inevitable frustration in the event they delete a comma or colon and then don't understand why nothing is working and there's loads of error messages.

I guess I am a little biased because I'm the type of person that likes to know every little detail about something so I understand it fully. So if I knew what the dictionary was and its associated syntax then I'd be more confident in what I'm doing. But indeed there could be some people who don't care about the detail and just want to use caster to complete whatever task they need. In this case your approach is best.

Just for context, when I first tried to dip my toe in the world of building grammars with dragonfly I didn't even know what a "directory" was or a "file path". So reading documentation back then was frustrating as it seemed it was written with the assumption that you are already a programmer. So I think it's great you are taking the approach that you are taking.

"If you were to totally restructure the documentation what would it look like in the table of contents?" Regarding my suggestions for restructuring documentation. I'm coming from a place where I have an incomplete knowledge of caster and rudimentary knowledge of Python as I'm only using Python in the context of data analytics. But I'm interested in learning more about caster and Python so I would be happy to help out in the documentation department if needed. I have exam crunch over the next 2 weeks but over the Christmas I could review more of the documentation or give ideas of how it could be best sequenced for programming no-hoper like myself! :-)

LexiconCode commented 3 years ago

I'm going to merge this now. We can open up new issue for further improvements as needed.

dictation-toolbox / Caster