Policy Notes for the Webel Parsing Analysis recipe for SysML

Icon class

icon_class_computed

fas fa-book

Keywords

Webel Parsing Analysis
super-relational
Policy Note

To learn how the policies and recommendations of these Policy Note pages are applied to the Webel Parsing Analysis recipe for SysML^® please visit this tutorial:

TRAIL: Theory and best practices for the Webel Parsing Analysis recipe for SysMLv1.6+

Each "super relational" Policy Note page is linked to one or more relevant content pages and/or one or more Snippet text extract quote pages and vice-versa.

Policy Notes for the Webel Parsing Analysis recipe for SysML^®

Currently NOT ordered or prioritised. The format is:


[NOTE_TYPE_TAG, ...]{POLICY_LEVEL_TAG} LINKED_TITLE

[POLICY]{STRICT} Webel Parsing Analysis: A custom Document stereotype (keyword «document») extends the UML standard profile Document that extends Artifact (which is NOT in the UML4SysML intersection). Such a Document may act as the 'source' of a «snippet».
[OPTION]{RECOMMENDED} TIP: If you use the name '0-source' instead of 'source' for the top-level Package/Model for containing Parsing Analysis elements it will list nicely at the top of the containment tree.
[MODELLING, NAMING, POLICY]{STRICT} Webel Parsing Analysis: While Associations may be collected as elicited members of a Snippet this can quickly lead to clutter in the /member list display. Often just collecting an end Property as member is sufficient.
[DISPLAY, LIMITATION]{INFORMATIVE} Webel Parsing Analysis: MagicDraw/Cameo: SysML1.6+: ElementGroup-based Snippets do not list in the compartment of Package/Model symbols because ElementGroup is based on the UML Comment, which does not list in Package/Model symbols.
[POLICY]{STRICT} Webel Parsing Analysis: A Snippet (keyword «snippet») MUST always have exactly one domain 'source' Document (keyword «document»).
[MODELLING, NAMING, POLICY]{RECOMMENDED} Webel Parsing Analysis: Where too many dashed line "anchors" from Snippets to elicited members lead to clutter they may be selectively omitted from a Parsing Analysis Diagram (PAD) once each member has been collected.
[TIP]{RECOMMENDED} Webel Parsing Analysis: It is not intended that you "parse and analyse" every sentence from every domain source document and map every word to your SysML model. The process adds incremental benefit; the more you use the WPA recipe, the better!
[ASSERTION]{TIP} Not even the most experienced requirements engineers can easily state requirements perfectly in consistent requirements-friendly language first shot; requirements and constraints are often buried in the natural text of domain source documents.
[TIP]{RECOMMENDED} Webel Parsing Analysis: Relationships between «snippet» items can be tracked using additional tagged values such as 'contradictedBy' and 'contradicts'. This is robust, but it can be verbose when Snippets have long names if the tagged values are displayed.
[MODELLING, NAMING, POLICY]{STRICT} Webel Parsing Analysis: The name of a Parsing Analysis Diagram (PAD) may be drawn from a focus Snippet OR may simply indicate a topic of interest to the analysis
[EXPLANATION, MODELLING]{STRICT} Webel Parsing Analysis for SysML: "Snippet trumps Requirement": A SysML Requirement element is just another model element that is elicited IN PARALLEL WITH other elements that a text description mentions in any way as being involved with or related to it.
[ASSERTION]{INFORMATIVE} Webel Parsing Analysis is a "meta-process" that can be applied to general domain source documents to elicit Requirements (and related model elements) or to a Requirements Specification itself as a special case of a domain source document!
[POLICY]{STRICT} Webel Parsing Analysis diagrams do their job once - namely traceable elicitation of model elements - and are then only kept as a reference! The elicited model elements are then used elsewhere in the final model.
[ASSERTION]{SUGGESTED} Webel Parsing Analysis: A stereotype with keyword «pa:from» may be applied to a Dependency from a Package to another Package within the Source Input Zone to indicate that all of its Elements were directly or indirectly elicited from source Documents.
[ASSERTION]{TIP} Humans work well with natural language: Many stakeholders – including those who are not necessarily familiar with UML or SysML modelling symbols and diagrams - benefit enormously from having plain text in diagrams side-by-side with graphics.
[TIP]{INFORMATIVE} In professional applications of the Webel Parsing Analysis recipe for SysML, a robust reusable profile for «part»/«assembly»/«leaf» components is used, along with stereotypes keywords like «assembles» for indicating physical composition hierarchies.
[POLICY]{STRICT} Webel Parsing Analysis: A 'source' Document must have one (only) of a URL or a URN (includes ISBN or other unique identifier) for use as a URI
[ASSERTION]{TIP} Translating authoritative technical documents written in “natural” engineering language (snippet-by-snippet) into Webel Parsing Analysis diagrams creates consistent underlying systems models and can bridge easily to existing methodologies.
[TIP]{INFORMATIVE} In Webel Parsing Analysis tutorials, Wikipedia pages are often used as a placeholder sources to represent authoritative domain source documents from which text extract "snippets" are sourced, and from which SysML model elements are traceably elicited.
[CONVENTION, MODELLING, TIP]{RECOMMENDED} Webel Parsing Analysis: It does not matter whether you use a Package or a Model package. (The informal Webel convention is that Models are used for systems engineering analysis with SysML and Packages are reserved for code-related software engineering.)
[ASSERTION]{TIP} Even relatively informal elicitation of model elements using the SysML ElementGroup and a Parsing Analysis approach is extremely powerful.
[POLICY]{TIP} In the Webel Parsing Analysis recipe you are not obliged to map every single part of a Snippet's text extract to a UML or SysML model, just traceably elicit model elements of immediate or anticipated interest to your task or goal.
[CAPABILITY, FEATURE, NAVIGATION, TIP, TOOL]{RECOMMENDED} Webel Parsing Analysis: If you have a unique URL for a domain source «document» you MAY additionally set it as an external hyperlink in the MagicDraw/Cameo tool (as well as setting it as the unique 'url' tagged value that acts as the '/uri').
[TIP]{INFORMATIVE} The Webel Parsing Analysis recipe for SysML1.x does not use the ElementGroup directly, it extends it as a user-defined Snippet stereotype with keyword «snippet» and with MagicDraw Customization.
[ASSERTION]{TIP} The Webel Parsing Analysis recipe promotes a clearly scoped modelling workflow.
[QUESTION]{STRONG} Webel Parsing Analysis: SysMLv1.x: Q: "Instead of using a Snippet extension of an ElementGroup, can't I just use a Requirement and Trace to achieve the same thing?" A: No! The ElementGroup extended as the Snippet is far more powerful and fit for purpose.
[DISPLAY, MODELLING, NAMING, POLICY, TIP]{STRICT} Webel Parsing Analysis: Pseudo Semantic Triple: For «pa:triple» applied to a named one-to-one or one-to-many uni-directional Association, the non-navigable end Property is the subject, the name is the predicate, the navigable end Property is the object.
[TIP]{INFORMATIVE} The grouping of member elements by an ElementGroup is denoted here "logical" in the sense that it does not "steal ownership" of member elements (as opposed to "physical" ownership of elements in the model)
[ASSERTION]{INFORMATIVE} Webel Parsing Analysis (with strict traceability of all elicited model elements) can be used side-by-side with "freestyle" modelling with incremental benefit the more it is used.
[QUESTION]{INFORMATIVE} SysMLv1.x: Q: Why can't a Package with PackageImports be used as a Parsing Analysis text container? Why is the SysML1.6 ElementGroup (extended and customised as the Webel «snippet») far better suited for text-driven model element elicitation?
[DISPLAY, MODELLING, NAMING, POLICY, TIP]{STRICT} Webel Parsing Analysis: Pseudo Semantic Triple: For «pa:triple» applied to a named one-to-one Dependency, the source is the subject, the name of the Dependency is the predicate, the target is the object.
[OPTION]{RECOMMENDED} In Webel Parsing Analysis if you want to track elicited model elements that have not been explicitly mentioned in source text you can introduce Element-level custom tracking Stereotypes with the keywords «pa:implied» or «pa:assumed».
[TIP]{EDITORIAL} In Webel Parsing Analysis every Package, Model, or Diagram used to perform Parsing Analysis MUST have the stereotype keyword «pa» applied, and MUST live under a top-level Model or Package 'source' separate from the rest of the project model.
[MODELLING]{INFORMATIVE} SysMLv2: On the v2 Comment extension of the v2 AnnotatingElement as a candidate Parsing Analysis Container
[DISPLAY, MODELLING, NAMING, POLICY, TIP]{STRICT} Webel Parsing Analysis: Pseudo Semantic Triple: When «pa:triple» is applied to a named uni-directional Association the name and a consistent direction arrow should be displayed on the Association symbol in diagrams.
[CONVENTION, TIP]{STRONG} Webel Parsing Analysis: typically the quoted extract text (body) of a «snippet» is a short phrase, a sentence, or a couple of short sentences (but not dozens of sentences).
[ASSERTION]{STRICT} In Webel Parsing Analysis elicited model elements MUST eventually be moved out of the 'source' (or '0-source') Package/Model zone and under a main project Package/Model area. (Use the owner display option to check.)
[TIP]{INFORMATIVE} Webel Parsing Analysis: The absolute basics of the process (SysMLv1.x form)
[MODELLING, POLICY]{STRICT} Webel Parsing Analysis: SysML: Pseudo Semantic Triple: A «pa:triple» may be applied to a Dependency between SysML Blocks and/or Actors or Properties typed by them.
[POLICY, STYLE]{STRICT} Webel Parsing Analysis «pa» diagrams are NOT intended as final presentation diagrams! They serve merely to traceably elicit model elements, which may then be shown in other (typically much tidier) presentation diagrams elsewhere.
[DISPLAY, STYLE, TIP]{SUGGESTED} Webel Parsing Analysis: If the dashed-line "anchors" from your «snippet» ElementGroup symbols to elicited elements make a «pa» Parsing Analysis Diagram (PAD) too hard to read, try making them light grey using symbol properties.
[MODELLING, POLICY, TOOL]{STRICT} Webel Parsing Analysis: As StateMachine Diagrams are always owned by an element that is not eventually under the Source Input Zone they should not be used as «pa» diagrams. Elicit States instead via the /member section of the specification dialog.
[MODELLING, POLICY]{STRICT} Webel Parsing Analysis: SysML: Pseudo Semantic Triple: A «pa:triple» may be applied to a uni-directional Association between SysML Blocks and/or Actors.
[ASSERTION, DISPLAY, POLICY, SETTINGS, STYLE, TOOL]{STRICT} Webel Parsing Analysis: If you wish to show a «snippet» comment symbol (with its body text) in a presentation diagram (that is NOT a «pa» diagram) remove the '/member' tagged value from display so the only visible tagged value is 'source'.
[TIP]{SUGGESTED} Webel Parsing Analysis: You may create custom stereotypes applicable to a Dependency or a uni-directional Association to represent a «predicate» much like a semantic triple (subject-predicate-object) in OWL/RDF.
[MODELLING, NAMING, POLICY]{STRICT} Webel Parsing Analysis: Acronym: PAD = Parsing Analysis Diagram (may be nearly any diagram type, except those types that must be owned by an elicited model element)
[OPTION]{STRONG} Webel Parsing Analysis: Formally, if «pa:implied» has been applied to indicate an implied elicited Element, the 'snippet' tagged value should bet set using at least one Snippet that implies it. (Note, the Snippet should have identical 'name' and 'body'.)
[TIP, TOOL]{RECOMMENDED} Webel Parsing Analysis: If you are processing lots of text from one source «document» create a STUB «snippet» with that «document» set as 'source' and just make copies of it in the model browser as needed. Big time saver!
[TIP]{SUGGESTED} Webel Parsing Analysis: You do not need to map every word of every snippet to the UML/SysML model! Extract only the information required for your domain modelling task to add incremental benefit.
[DISPLAY, MODELLING, POLICY]{STRONG} Webel Parsing Analysis: A "focus" Parsing Analysis Diagram (PAD) for one or more Snippets SHOULD always show the /member tagged value of every Snippet.
[OPTION]{RECOMMENDED} Webel Parsing Analysis for SysML: Track and display alternative names, human friendly names, organisation-specific names, and identifiers using tagged values for a custom stereotype «pa:term» (adapt or extend as required).
[POLICY, STYLE]{STRICT} Webel «pa» Parsing Analysis Diagrams (PADs) are "scratchpads" used to elicit model elements traceably from text Snippets (extracts from source Documents). While BDDs are a good initial choice, most types of SysML diagram can be used as a «pa» diagram.
[CAVEAT]{INFORMATIVE} One limit of the SysML-1.6 ElementGroup for use as a Snippet in the v1.x version of Webel Parsing Analysis for SysML is that an ElementGroup is not directly relatable.
[MODELLING, NAMING, POLICY]{RECOMMENDED} Webel Parsing Analysis: An anonymous Element may be collected as a /member of a Snippet (it is not important whether collected elements list with a clear name under /member, only that they are traceably elicited).
[CAPABILITY, TIP]{INFORMATIVE} The SysML Trace relationship can be used as a quick way to traceably elicit model elements from an identified diagram or table from a domain source document. You may visually remove the Trace symbols as each element is elicited to reduce clutter.
[POLICY]{STRICT} Webel Parsing Analysis: Create a top-level 'source' or '0-source' Package/Model SEPARATE from your project model. All source «document» elements and «snippet» extracts and «pa» diagrams MUST be ultimately owned by that top-level Package/Model as ancestor!
[TIP]{RECOMMENDED} Webel Parsing Analysis: MagicDraw/Cameo: In parsing diagrams use the element compartment properties to only display the features relevant to the context of a particular snippet's text extract.
[MODELLING, NAMING, POLICY]{STRICT} Webel Parsing Analysis: While Generalizations may be collected as elicited members of a Snippet this can quickly lead to clutter in the /member list display.
[DISPLAY, MODELLING, OPTION]{INFORMATIVE} Webel Parsing Analysis: An "index" Parsing Analysis Diagram (PAD) showing a collection of Snippets may optionally (but need not always) show the /member tagged value of each Snippet.
[CAVEAT, ISSUE]{INFORMATIVE} The markup of Snippet page titles on this CMS web site is sometimes restricted (especially concerning subscripts and superscripts such as used in mathematical and scientific notation). Visit the linked Snippet page for the quote with full markup.

Notes

Relevant snippets (from other sources)

Visit also

The Webel Parsing Analysis recipe for SysML

Webel's Best Practice policy notes for MBSE with SysML1.x (and UML) and the MagicDraw/Cameo tools

The Webel Digital Twin Pattern for SysML policy notes

Visit also (backlinks)

Flags

Policy Notes for the Webel Parsing Analysis recipe for SysML

Policy Notes for the Webel Parsing Analysis recipe for SysML®

Policy Notes for the Webel Parsing Analysis recipe for SysML^®