Closed peter-michalski closed 1 year ago
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.
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.
Completely agree with @smiths .
../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.
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')
.
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.
Clarify adding terms to TermMap.
(nw websitelayout : nw website : [nw program]
Really great documentation about what's currently wrong. What's the plan forward?
Below is a summary of the changes that I will make to the tutorial (and related files):
Adding Sections to SRS Body
section 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.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.Adding Introduction Section
tutorial section.Adding Introduction Section
.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.Adding Introduction Section
's sixth step that the user must also import Data.Drasil.Concepts.Documentation as Doc (doccon, doccon')
.Adding Introduction Section
's sixth step explaining what symbMap does and how to populate it. Link to other examples.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.Adding Specific System Description (SSD) Section
's first step that terms
is defined as a ConceptChunk
.correctness
in softwarecon
in software concepts.Adding Specific System Description (SSD) Section
's second step that a figure is only needed if adding a PhySysDesc
subsection.Add your module to package.yaml
comment from many SectionsAdding Assumptions Section
that Assumptions are added with the Assumptions
constructor under the SSDSolChSpec
constructor in the Specific System Description
sectionAdding Theoretical Models Section
that Theoretical Models are added with the TMs
constructor under the SSDSolChSpec
constructor in the Specific System Description
sectionAdding General Definitions Section
that General Definitions are added with the GDs
constructor under the SSDSolChSpec
constructor in the Specific System Description
sectionAdding 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. Adding Instance Models Section
that Instance Models are added with the Ims
constructor under the SSDSolChSpec
constructor in the Specific System Description
sectionAdding 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
sectionAdd the requirement sections and subsections to the Drasil.DocLang import list
add to package.yaml
from the third step of Adding Requirements Section
Adding Likely and Unlikely Changes Section
. Point to the example that uses itAdding Other Sections
. Point to GamePhysics Body.hs since it has this section.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.
@smiths I can add a comment in the updated tutorial that the instructions are for commit b555167ce688040b766742b03442fbf7af750087 on 29 Oct 2022.
The wiki tutorial is now updated.
Indeed, nice thorough list. And thanks for the fixes.
Can you speculate about the following things:
This issue is not the best place to 'do' such speculation - probably a Discussion would be better suited.
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'.