A meta-analysis of PR #3059

[JacquesCarette]

This is a record of my thoughts as I was analyzing @peter-michalski 's changes in #3059. Note that this PR is merged, so it met the quality bar for making it into Drasil's code base. So now I'm going to deconstruct it thoroughly - not as a complaint, but as a means to move Drasil forward. These observations are not ordered, but rather "as they occur to me" as I look at the code again.

First, it should be clear that a 10 argument function like

Drasil/code/drasil-website/lib/Drasil/Website/About.hs

Lines 9 to 11 in 1ab7a8c

	-- | Creates the about section.
	aboutSec :: Reference -> Reference -> Reference -> Reference -> Reference -> Reference -> Reference -> Reference ->
	Reference -> Reference -> Section

is rather outrageous. Is it likely to ever by called by anything other than the exact 10 arguments that it has? No. In that sense, it is pointless abstraction.

But in another sense, this function is great! It captures the fact that the currently generated "about section" of the web site is composed of 10 different pieces, each of which communicates a different idea. So there is meta-information contained in this. Also, if we chose to re-order the paragraphs, it would be easy. Would it make sense? Maybe not: maybe the paragraphs are in this order because of dependencies, flow, etc. We don't know.

We also spot a Drasil anti-pattern:

Drasil/code/drasil-website/lib/Drasil/Website/About.hs

Lines 13 to 18 in 1ab7a8c

	section (S "About") -- Title
	(map mkParagraph [aboutParagraph1 repoRef wikiRef, aboutParagraph2 csRef docRef analysisSecRef, aboutParagraph3]
	++ [currentlyGeneratedArtifacts] ++ [mkParagraph aboutParagraph4] ++ [futureGeneratedArtifacts] ++ map mkParagraph
	[aboutParagraph5 infoEncodingWiki, aboutParagraph6 chunksWiki, aboutParagraph7 recipesWiki, aboutParagraph8 paperGOOL,
	aboutParagraph9 papersWiki]) -- Contents
	[] $ makeSecRef "About" $ S "About" -- Section reference

The word About is repeated 3 times.

Moving on to the next function

Drasil/code/drasil-website/lib/Drasil/Website/About.hs

Lines 20 to 28 in 1ab7a8c

	-- | Paragraph to about Drasil and its goals.
	aboutParagraph1 :: Reference -> Reference -> Sentence
	aboutParagraph1 repoRef wikiRef = S "Drasil is a framework for generating all of the software artifacts \
	\from a stable knowledge base, focusing currently on scientific software. The main goals are to reduce knowledge \
	\duplication and improve traceability. The artifacts are generated from a common knowledge-base using recipes \
	\written in a Domain-Specific Language (DSL). These recipes allow us to specify which pieces of \
	\knowledge should be used in which artifacts, how to transform them, and more. For more information on the design, documentation, \
	\useage, and specifics of Drasil, please visit the" +:+ namedRef repoRef (S "GitHub repository") +:+ S "or the" +:+
	(namedRef wikiRef (S "GitHub Wiki") !.)

We see some obvious stuff (like "Drasil" and "DSL" and other such text) that is inlined instead of re-used. More problematic in a sense are the inlined references like namedRef repoRef (S "GitHub repository"). More subtly, we notice that the comment above the function "Paragraph to about Drasil and its goals", 1) contains a grammar error / typo, 2) is more informative than aboutParagraph1. Also we notice something else: that it is described as a "paragraph" but its type is Sentence. Quite odd.

A little further down:

Drasil/code/drasil-website/lib/Drasil/Website/About.hs

Lines 46 to 51 in 1ab7a8c

	currentlyGeneratedArtifacts :: Contents
	currentlyGeneratedArtifacts = enumBulletU $ map foldlSent_
	[[S "SRS"],
	[S "code"],
	[S "README"],
	[S "Makefile"]]

this is a fantastic (missed) opportunity for some meta-Drasil. First, I'm quite sure that all 4 of these concepts already exist in our 'database', and should have been pulled from that. Second, I'm pretty sure that there is a combinator for enumBulletU $ map foldlSent_ that already exists. But, most importantly, this "list" of generated artifacts should be inside Drasil somewhere, with the information as Chunks that link up the concepts with the data-structures and code that "make it so".

Of course, we're also struck that this is all a very odd way to do things: this embedding of such much text in Haskell is just weird. This is not wrong, but is what our current design asks for. It's our current design that is weird. Something like a Drasil-flavoured Markdown (say), or Drasil-flavoured org-mode might be better.

(There are similar issues with other parts of the code in this file, but nothing conceptually new)

Jumping to a different file, we see

Drasil/code/drasil-website/lib/Drasil/Website/Body.hs

Lines 130 to 156 in 1ab7a8c

	-- | Used for the repository link.
	gitHubRef :: Reference
	gitHubRef = makeURI "gitHubRepo" gitHubInfoURL (shortname' $ S "gitHubRepo")
	wikiRef :: Reference
	wikiRef = makeURI "gitHubWiki" (gitHubInfoURL ++ "/wiki") (shortname' $ S "gitHubWiki")
	infoEncodingWiki :: Reference
	infoEncodingWiki = makeURI "InfoEncodingWiki" (gitHubInfoURL ++ "/wiki/Information-Encoding") (shortname' $ S "InfoEncodingWiki")
	chunksWiki :: Reference
	chunksWiki = makeURI "chunksWiki" (gitHubInfoURL ++ "/wiki/Chunks") (shortname' $ S "chunksWiki")
	recipesWiki :: Reference
	recipesWiki = makeURI "recipesWiki" (gitHubInfoURL ++ "/wiki/Recipes") (shortname' $ S "recipesWiki")
	paperGOOL :: Reference
	paperGOOL = makeURI "GOOLPaper" (gitHubInfoURL ++ "/blob/master/Papers/GOOL/GOOL.pdf") (shortname' $ S "GOOLPaper")
	papersWiki :: Reference
	papersWiki = makeURI "papersWiki" (gitHubInfoURL ++ "/wiki/Drasil-Papers-and-Documents") (shortname' $ S "papersWiki")
	quickStartWiki :: Reference
	quickStartWiki = makeURI "quickStartWiki" (gitHubInfoURL ++ "#quick-start") (shortname' $ S "quickStartWiki")
	newWorkspaceSetupWiki :: Reference
	newWorkspaceSetupWiki = makeURI "newWorkspaceSetupWiki" (gitHubInfoURL ++ "/wiki/New-Workspace-Setup") (shortname' $ S "newWorkspaceSetupWiki")
	contribGuideWiki :: Reference
	contribGuideWiki = makeURI "contribGuideWiki" (gitHubInfoURL ++ "/wiki/Contributor's-Guide") (shortname' $ S "contribGuideWiki")
	workflowWiki :: Reference
	workflowWiki = makeURI "workflowWiki" (gitHubInfoURL ++ "/wiki/Workflow") (shortname' $ S "workflowWiki")
	createProjWiki :: Reference
	createProjWiki = makeURI "createProjWiki" (gitHubInfoURL ++ "/wiki/Creating-Your-Project-in-Drasil") (shortname' $ S "createProjWiki")
	debuggingWiki :: Reference
	debuggingWiki = makeURI "debuggingWiki" (gitHubInfoURL ++ "/wiki/Debugging-in-Drasil") (shortname' $ S "debuggingWiki")

which is a real missed opportunity for abstraction. There are clear patterns here that should be taken advantage of.

In the new module Drasil.Website.GettingStarted, I don't see any new class of "missed opportunities", but most definitely a lot of room for applying Drasil ideas to itself. Certainly there is a lot of duplicated text. And the missed opportunity of creating chunks based on web concepts and documentation concepts. Transforming the code in that way would likely make it much more "conceptually clear", and even more exciting, exposed larger scope concepts ready to be abstracted.

[peter-michalski]

Just some initial thoughts..

We see some obvious stuff (like "Drasil" and "DSL" and other such text) that is inlined instead of re-used.

Could you elaborate on this further? Is there a combinator for these that I should have used?

More problematic in a sense are the inlined references like namedRef repoRef (S "GitHub repository").

Similarly, do you mean that I should have used an existing combinator, or alternatively that a combinator should be created for these?

I'm quite sure that all 4 of these concepts already exist in our 'database', and should have been pulled from that.

I'm not familiar with implementing this. How can I pull specific concepts from the database here? Is there a resource that details pulling specific information from the database? I also wonder if the database will have this information if I only make website.

[JacquesCarette]

We see some obvious stuff (like "Drasil" and "DSL" and other such text) that is inlined instead of re-used.

Could you elaborate on this further? Is there a combinator for these that I should have used?

Turns out, there isn't. (I used 'ripgrep' to search through all our sources for those strings, including the quotation marks). But the duplication is a sure signal that it ought to be defined as a chunk in drasil-data.

More problematic in a sense are the inlined references like namedRef repoRef (S "GitHub repository").

Similarly, do you mean that I should have used an existing combinator, or alternatively that a combinator should be created for these?

Yes. I am pretty sure there is such a function - but if there isn't, then it should be created.

I'm quite sure that all 4 of these concepts already exist in our 'database', and should have been pulled from that.

I'm not familiar with implementing this. How can I pull specific concepts from the database here? Is there a resource that details pulling specific information from the database? I also wonder if the database will have this information if I only make website.

By 'database' I mean the data-drasil package and its contents. Most examples use it already - peek at Projectile for example.
Being very familiar with that is in all of data-drasil is a very good idea.