Use consistent terms: run_start -- there is no such document

[prjemian]

During review of PR #94, I raised this point

When this was all new to me, the two terms "Event Descriptor" and "descriptor" as a document schema did not jump out as being the same thing. Run Start/start and Run Stop/stop similar but somehow easier to grasp. Gradually, this struck home.

Is this the time to make this crystal clear for the neophytes? The [bluesky project applies new definitions to otherwise familiar terms and this] is daunting to new users.

The suggestion was to make a new PR which should be created after #94 is merged.

Expected Behavior

If there is a document schema such as start, it should be referred to consistently as such, not as run_start or Run Start. There is no run_start document.

Current Behavior

The documentation is inconsistent in how it refers to the various document types (schemas).

Possible Solution

Editing and revision through PR process. All the document types should be reviewed for consistent reference. The exact name of the document type should be used, such as run 'start' (rather than 'run_start').

Steps to Reproduce (for bugs)

n/a

Context

As stated, the inconsistent references to the same document schema created confusion and delay for me when this material was all new, when trying to write my first callback routine.

Seeing the revisions of PR #94 (especially when gathering the resource and datum descriptions with the others) gave me the idea this was the time to note the inconsistent handling.

Your Environment

n/a

[danielballan]

This is valuable feedback. I am favor of making this change. In any place where we are writing code or naming files we should use 'start' and 'descriptor' consistently. I am still in favor of using the full names like Event Descriptor document and Run Start document in narrative text. Not sure where @prjemian lands on that point.

[prjemian]

That's ok. What stymies the newcomer is the expansion of the vocabulary to be learned. For example, we can say that Run Start is the 'start' document. Works for me.

…

On Thu, Aug 1, 2019, 11:00 AM Dan Allan ***@***.***> wrote: This is valuable feedback. I am favor of making this change. In any place where we are writing *code* or naming *files* we should use 'start' and 'descriptor' consistently. I am still in favor of using the full names like Event Descriptor document and Run Start document in narrative text. Not sure where @prjemian <https://github.com/prjemian> lands on that point. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#102?email_source=notifications&email_token=AARMUMFQNZFZ2UT5YL5DXZ3QCMCBLA5CNFSM4IIRNTN2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD3LCHOA#issuecomment-517350328>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARMUMHRV3NC3JRNI6Z5F7LQCMCBLANCNFSM4IIRNTNQ> .

[danielballan]

Great, we're exactly on the same page then. 👍