Update 'Creating Your Project in Drasil' Wiki

[peter-michalski]

This issue is for updating the above wiki page as I build a Drasil example. Updating the workflow to include wiki maintenance might be a good idea, and be worth an issue or discussion page. Is it possible that, as Drasil is developed, updates to the wiki are sometimes forgotten? It would be unfortunate if potential contributions to the project are abandoned because deprecated manuals decrease usability.

Following the advice of @JacquesCarette in #3067, I have started to build an SRS for the website by creating a 'Drasil example'. The initial commit is e3d112d620a7386526af5e27acce75141f2ec7cc.

As I was setting up the base files following the Creating Your Project in Drasil wiki, I noticed that the yaml and cabal file section must be out of date. The yaml and cabal files are currently housed within each example, but the wiki page suggests that there is one common yaml file in /code/drasil-example/package.yaml. I'm not sure if this is a typo or if indeed this used to be the case regarding yaml files in Drasil.

Either way, there may be more typos or deprecated instructions. I will document potential typos or deprecated instructions as I proceed with the 'website example'.

[peter-michalski]

This now has me wondering how quickly (quantifiably) various types of users (of software in general, not Drasil specifically) give up when encountering out of date documentation.

[smiths]

Excellent observation @peter-michalski. I know for a fact that at least some people give up when they encounter out of date documentation, because I've certainly done that! My son was just telling me about all the headaches he had with a highschool programming project because the library he was using was no longer maintained, but he didn't know that at the outset of the project. Something that should have been easy took hours of time, and then had to be abandoned to do the task a different way.

That is one of the selling features of Drasil in Drasil. If Drasil could generate its own documentation and the documentation was always current, we wouldn't have the documentation challenges you are eluding to. Unfortunately, the problems you found in our instructions are because they were written manually, and not fully maintained.

Please continue as you have suggested and watch for typos and deprecated instructions.

[JacquesCarette]

Completely agree with @smiths .

[peter-michalski]

• ../code/drasil-docLang/Drasil/DocLang/SRS path is out of date

• The following suggested import is out of date:

  import Drasil.DocLang (AuxConstntSec(AuxConsProg),DerivationDisplay(ShowDerivation),
  DocSection(TableOfConstantsAuxConstntSec, Bibliography, IntroSec, RefSec, ReqrmntSec, SSDSec, TraceabilitySec), 
  Emphasis(Bold), Field(..), Fields, InclUnits(IncludeUnits),IntroSec(..), IntroSub(IScope), ProblemDescription(PDProg), 
  PDSub(..),RefSec(..), RefTab(..), ReqrmntSec(..), ReqsSub(..), SCSSub(..), SRSDecl, SSDSec(..), 
  SSDSub(SSDProblem, SSDSolChSpec), SolChSpec(SCSProg), TConvention(..), TSIntro(..), 
  TraceabilitySec(TraceabilityProg), Verbosity(Verbose), intro, mkDoc, traceMatStandard, tsymb, purpDoc)

  DocSection constructors now reside in several locations, but Drasil.SRSDocument module imports all of them. Consequently, Body.hs must import Drasil.SRSDocument. We could replace the current instructions with this blurb, add an example of the syntax for adding sections, and finally add a note that a complete list of current constructors can be found in Drasil docLang Haddock . Linking to Haddock should help prevent these instructions from going out of date.

[peter-michalski]

• 9. At this point build your code (by running make) and see what you generate. You should see the sections in step 5 displayed in your SRS. is out of date. Simply adding constructors (with dummy data) to mkSRS and running make will result in an error <your-example>: Term: content not found in TermMap. Looks like (at least) ChunkDB needs to be populated before building the example. This step should be moved to later in the tutorial, or additional steps should be added before it. Course of action should be more clear once one pass of the tutorial is complete.

• 5. Since we added a scope section, you will need to include the constructor name in the chunk database. scope is defined in the doccon constructor in ../drasil-data/Data/Drasil/Concepts/Documentation. It might help to clarify that every section that is added by the user will already need to be specified as a constructor in the chunk database. The user cannot add their own arguments to the DocSection constructors. Or can they? In this case these sections will not be recognized as chunks?

• 6. In the 3rd argument of symbMap, add the doccon and doccon' functions. The third argument should now look like: This step is quite confusing at first. The symbMap code found in current Drasil examples looks quite different once symbMap is filled in. There may be usability issues for someone who is not familiar with Haskell and familiar with Drasil. The time spent figuring things out could be greatly reduced if the symbMap code from Template/Body.hs (shown below) had a comment and/or there was an explanation in the tutorial. Must also import Data.Drasil.Concepts.Documentation as Doc (doccon, doccon').

https://github.com/JacquesCarette/Drasil/blob/4e40ad9860c3cba87e905ba455ef5f7eb8b75d2e/code/drasil-example/template/lib/Drasil/Template/Body.hs#L43-L47

[peter-michalski]

• Adding Specific System Description (SSD) Section

The tutorial appears, when referencing the Haddock documentation, to skip several potential sections at this point. We should consider adding a comment here that a full list of potential sections can be found at that link, and that not all sections need to be included. A similar comment exists near the bottom of the tutorial, but should probably be moved higher. Either here or near the top of the tutorial.

• Before you add the SSD section, you will need to define the following parameters in Body.hs using Sentence types:

terms is defined as a ConceptChunk in other examples.

Side note: correctness is defined twice in software concepts

• Create a new file Figures.hs for your physical system diagram and define a function for your figure.

Slope Stability has figures.hs, but does not import figure.hs. A figure is required for PhySysDesc.

• Add your module to the import list in Body.hs to display your Goal statement section and update symbMap as required. Add goals to your symbMap or to concIns (which will be created in step 10 of the next section).

symbMap really needs more of an explanation. I'm about half-way through the tutorial and it's not clear how to use it, and what it is really for. The tutorial does identify this as the chunk database, but this needs more explanation, and its importance needs highlighting. Furthermore, there is no step 10 in the next section, step 10 is missing. At this point it is not clear where to update symbMap. I needed to reference other examples to figure out what concIns is and where to add it.

• 10. Add your module to package.yaml

This is not done in any example.

• Adding Assumptions Section

Should add a note that this needs to be added within SSDSolChSpec of SSDProg. This section also has an unnecessary comment about adding modules to package.yaml

• Adding Theoretical Models Section

Same comments as for the assumptions section. Also need to update some paths.

• Adding General Definitions Section

Same comments as for the theoretical models section.

• Adding Data Definitions and Acronym Section

Same comments as for the theoretical models section.

• Adding Instance Models Section

Same comments as for the theoretical models section.

• Adding Constraints and Properties of a Correct Solution Section

Same comments as for the theoretical models section.

• 2. Add the requirement sections and subsections to the Drasil.DocLang import list:

This is not needed.

• 3. ...and add to package.yaml.

This is not needed.

• 5. ...See code/drasil-lang/Language/Drasil/Chunk/Concept.hs for constructor info.

Update path.

• Adding Likely and Unlikely Changes Section

This section is not clear. A sample of examples do not have this section to reference.

• Adding Other Sections

Same as above. Only GamePhysics uses this.

• Update paths in rest of tutorial

[peter-michalski]

• Term: website not found in TermMap

Clarify adding terms to TermMap. (nw websitelayout : nw website : [nw program]

[JacquesCarette]

Really great documentation about what's currently wrong. What's the plan forward?

[peter-michalski]

Below is a summary of the changes that I will make to the tutorial (and related files):

• Update paths throughout tutorial as needed
• Update imports throughout the tutorial as needed
• Add a link to Haddock DocSection in the Adding Sections to SRS Body section
• Step nine of Adding Sections to SRS Body should note that depending on what you have added to mkSRS you may need to update the ChunkDB, which will be explained below.
• Add a step at the end of Adding Sections to SRS Body that notes that the remainder of the tutorial will go over adding a subset of potential sections to the project, and that a compelte list of potential sections can be found in the Haddock documentation. Not all sections need to be included in the project.
• Once again link to the Haddock documentation at the beginning of the Adding Introduction Section tutorial section.
• Add a point to define the IntroProg justification constructor In the Adding Introduction Section.
• Add a sentence to Adding Introduction Section's fifth step that the process of including the constructor name in the chunk database may need to be done when building other sections of mkSRS.
• Add a comment to Adding Introduction Section's sixth step that the user must also import Data.Drasil.Concepts.Documentation as Doc (doccon, doccon').
• Add a comment to Adding Introduction Section's sixth step explaining what symbMap does and how to populate it. Link to other examples.
• Add a brief comment to symbMap in Template/Body.hs explaining what symbMap does and how to populate it. Alternatively, add a comment in the code pointing to the tutorial so that way we do not have to maintain this information twice.
• Add/update a comment to Adding Specific System Description (SSD) Section's first step that terms is defined as a ConceptChunk.
• Remove one instance of correctness in softwarecon in software concepts.
• Add a comment to Adding Specific System Description (SSD) Section's second step that a figure is only needed if adding a PhySysDesc subsection.
• Clean up the numbering throughout the tutorial. Steps have been deleted but the step numbers have not been updated.
• Remove the Add your module to package.yaml comment from many Sections
• Add a comment to Adding Assumptions Section that Assumptions are added with the Assumptions constructor under the SSDSolChSpec constructor in the Specific System Description section
• Add a comment to Adding Theoretical Models Section that Theoretical Models are added with the TMs constructor under the SSDSolChSpec constructor in the Specific System Description section
• Add a comment to Adding General Definitions Section that General Definitions are added with the GDs constructor under the SSDSolChSpec constructor in the Specific System Description section
• Add a comment to Adding Data Definitions and Acronym Section that Data Definitions are added with the DDs constructor under the SSDSolChSpec constructor in the Specific System Description section. Acronyms are defined in a new file. Link to two examples, one with them defined in Defs and another in Unitals.
• Add a comment to Adding Instance Models Section that Instance Models are added with the Ims constructor under the SSDSolChSpec constructor in the Specific System Description section
• Add a comment to Adding Constraints and Properties of a Correct Solution Section that Constraints are added with the Constraints constructor and Properties of a Correct Solution are added with the CorrSolnPpties constructor under the SSDSolChSpec constructor in the Specific System Description section
• Remove the comment Add the requirement sections and subsections to the Drasil.DocLang import list
• Remove add to package.yaml from the third step of Adding Requirements Section
• Clarify Adding Likely and Unlikely Changes Section. Point to the example that uses it
• Clarify Adding Other Sections. Point to GamePhysics Body.hs since it has this section.

[smiths]

Very thorough @peter-michalski! Is there a logical place for us to record the version of Drasil (current commit hash, or maybe a tag?) for which the instructions are correct? Over time they will get out of date again (unfortunately), so until we automatically generate the wiki, it would be good to know the baseline.

I'll also ask for you to keep an eye on any changes to Drasil so that we remember when the project instructions get out of date again.

[peter-michalski]

@smiths I can add a comment in the updated tutorial that the instructions are for commit b555167ce688040b766742b03442fbf7af750087 on 29 Oct 2022.

[peter-michalski]

The wiki tutorial is now updated.

[JacquesCarette]

Indeed, nice thorough list. And thanks for the fixes.

Can you speculate about the following things:

• why did the tutorial drift so much?
• what could we have done (via human-process or technology or both) to prevent that?
• what else can we learn from the need to do all those fixed?

This issue is not the best place to 'do' such speculation - probably a Discussion would be better suited.