Improve Drasil Website 2

[JacquesCarette]

This issue is for "round 2" of #3039. The reason to split it out is to not let perfection be the enemy of the good/better. What is proposed there (and implemented in #3059) is very good indeed.

Furthermore, the very improvements made above are the reason that it is possible to see further improvements! All the things in this issue were entirely invisible before.

In many ways, what @smiths writes at the start of #3039 is a mini requirements document (audience / stakeholders, purpose). The "specific ideas/steps" then unfurl as a requirements gathering and analysis exercise. It reads like a (mini-)project plan, rather than as an issue per se. I see that maybe not all the steps identified here were actually done? That would be worth a round 2 on its own. Certainly there are excellent items that @peter-michalski pointed out that are not in #3059.

The other thing that I notice is that there is no difference between between the README (which is what people see when they land on our repo ) and our project web site. They serve different purposes, probably different audiences as well.

Yet another item is that both pages have grown to be quite long. Long enough that we should think about splitting things off.

But before we do any of that, we should really design these pages. Two things come to mind. First, we should build an SRS for the web site, as a Drasil example. Note that I don't expect to be able to use Drasil to generate the web site from this SRS - there will be some non-trivial gaps that we won't be able to close soon. But I think it's still a good exercise. Then we should use the SRS to make design decisions. We should document these decisions too. We can create a new document class in Drasil to contain that information, even if right now that information will be mostly English text.

This issue should be understood as a sort of meta-issue: a place to discuss the ideas outlined above. It ought to result in issues (and possibly some small projects) being generated, and that's when it can be closed.

[peter-michalski]

The other thing that I notice is that there is no difference between between the README (which is what people see when they land on our repo ) and our project web site.

I see some similarity, but not too much.

Both have some introductory/about information, as they should. It might be worthwhile to cut much of the introductory information from the README. The README should have a short blurb. The bulk of about-type information should be on the website.

Other than that, both the website and the README have information about Haddock documentation, the latter notes how to build Haddock locally, while the former links to Haddock documentation on the website. Keeping this as it is seems appropriate.

The website details Drasil examples, providing the user with some great background information, but it does not cover how to build and run them. The opposite is true for the README. This seems appropriate.

The Quick Start blurb on the website just links to the README, which is the appropriate location for the information.

The website also has other Getting Started information, which is just a series of links back to GitHub. We could move this to the README. It seems appropriate to move it considering that we already link to the README from the Quick Start subsection. The Getting Started section on the website could just be a blurb linking to the README.

The rest of the information on the website, including Case Studies and Analysis of Drasil, is appropriately placed.

Overall, information in the README should almost exclusively, aside from small blurbs or appropriate links, document the usage and development of the code.

[JacquesCarette]

I don't doubt your conclusions, but somehow I'd still like a deeper analysis. I'd like to explicitly know who the target audience is for each document, and what information each ought to provide (and why). I'm pretty sure the knowledge is in your head (as you must have used it to come to the above conclusions), but you didn't write it down in your comment.

[peter-michalski]

The Github.io webpage is used to showcase GitHub repos. It presents projects in a high level that requires less technical knowledge than that required of a code repository audience. For Drasil, the webpage audience includes various types of developers, scs users, and various types of researchers with interests in topics such as artifact generation and ontologies. The webpage should also interest potential graduate students to join the project. The target audience of the webpage is relatively broad when compared to the target audience of the README.

As noted by Prana et al., a key target audience for README files is developers. README files play an essential role in shaping developer's 'first impressions' and 'documenting the software project'. For Drasil, the README file target audience includes scs developers and users. Drasil users need to have some software development knowledge. Ideally, the webpage will introduce Drasil to its target audience and increase their interest enough for them to either follow/cite the project or, for a specific subset of these people, to drive them to the repository README and to test Drasil out.

Regarding the information in these artifacts, we need to avoid redundancy as much as possible for the sake of maintainability. The information should fall into either of these artifacts, or another artifact if appropriate. If information is useful to target audiences of both artifacts, then it should be placed into one of the artifacts and then linked to from the other artifact using a short blurb. Information that is technical (using/developing) should be in the README file, while high level information that describes the project should be on the webpage, which has a broader and less technical audience.

Classifying the information that is currently on both the webpage and the wiki README:

Information that should be on the webpage:

• A Quick Start link to the README in the repo for developers and users.
• The bulk of introductory/about information. This high-level information that is helpful for a broad audience.
• Details about the examples currently in Drasil. This showcases what applications Drasil generates artifacts for and provides sample output.
• Similarly, details in the Case Studies and Analysis of Drasil sections nicely showcase Drasil capabilities.
• A link to Haddock documentation that is on the same website.

Information that should be in the README:

• How to build Haddock locally. Generally, only developers and users will have a local copy of the documentation.
• How to actually build Drasil examples. Developers and users need to know how to do this.
• Getting Started information. Same as the point above, this information is for developers and users, and belongs with the code in the repo.

[JacquesCarette]

Regarding the information in these artifacts, we need to avoid redundancy as much as possible for the sake of maintainability.

Not if we use Drasil itself to generate them! Otherwise yes.

---

So one issue with the above analysis is that the README.md is also the landing page for the project on github.com. Many people are likely to arrive at Drasil here instead of on the https://jacquescarette.github.io/Drasil/ page. So we need to have some information for 'everyone' on both pages. I actually expect most people to start with the github.com page (i.e. the external README) and, if they are interested enough, move to what you call the 'webpage'.

The problem with Prana's analysis is that it is pre-github (?) in that the README text file was something included inside the development that you got after you downloaded and unpacked some software. But that's not true with README.md, as that doubles as the landing page.

So I think the audience of each needs to be revisited. Second, a pure classification is not nearly as interesting as a justified classification, i.e. a classification where there is an attached rationale for each classification decision.

[peter-michalski]

According to GitHub itself, GitHub.io websites are specifically meant to showcase projects to a broader audience (i.e. less focus on strictly developers). Considering this, and after reviewing the suggestions I had made for content in this artifact, many of the suggestions seem appropriate. Now if we are expecting most users to land on the README page first, then the content suggestions for this latter artifact indeed need to be revisited. I will need some more details as I fully revisit the issue.

Specifically,

1. As the owner of the project and artifact, what is your vision/intent for the usage and purpose of the website?
2. Other than search engine queries and links from the GitHub repo, is there anything else driving traffic to the website? For example, do Drasil presentations link to the repo and/or to the website? When you talk about Drasil to an audience, do you refer them to the repo or to the website? How would you describe these audiences that you may share Drasil with? This question also applies to other research team members.

I would also appreciate an expanded explanation of what is asked for regarding justified classification. I had provided rationale with the previous bullet points. I will expand on them below. Could you please let me know what further details I need to include or if there is a specific format that you are looking for?

In the meantime, as I try to fully understand the intent and traffic of the website, I will expand on my previous rationale below:

Information that should be on the webpage:

• Having a Quick Start link to the README is for developers and users and is helpful for those that initially land on the website and want to redirect to the repo. However, we already have a link to the repo at the top of the page, so this would be redundant. We could opt to discard the Quick Start link in the body of the webpage entirely. Alternatively, we could remove the link at the top, which is separated from the rest of the content by a large image. There is also nothing wrong with keeping both links. A user may appreciate the top repo link when they scroll to the very top of the page. They may also appreciate a link to the repo atop the body of the content of the page, since they will spend considerable time in this section of the page.
• The bulk of introductory/about information. This high-level information is helpful for a broad audience. It introduces the purpose and features of Drasil in a way that is digestible and of benefit to users, developers, researchers, and students. Considering what @JacquesCarette said about users landing on README, a greater portion of this information will need to appear in the README. It would indeed be best if the bulk of this content (minus the artifact specific blurbs and twin links) is generated in both artifacts if users initially land on both pages.
• Details about the examples currently in Drasil. This showcases what applications Drasil generates artifacts for and provides sample output. Since this is content that is not required for developers, it does not need to appear in the README. While some users do land on the README file, they can be redirected to the website for this content. This content is quite lengthy and exhaustive, and would make the README file increasingly difficult to navigate if it were entirely added there.
• A link to Haddock documentation that is on the same website. Intuitively, this useful information should be linked to from the home webpage, since it is on the same website.

Information that should be in the README:

• How to build Haddock locally. Generally, only developers and users will have a local copy of the documentation. They should not have to search hard to find out how to get a local copy of this information. It should be searchable on the landing page of the repo.
• How to actually build Drasil examples. Intuitively, basic usage information needs to be easy to find and belongs on the landing page. Developers and users need this information and it needs to be searchable on the landing page of the repo.
• Getting Started information. Same as the point above, this information is required for developers and users, and belongs with the code in the repo. This information needs to be easy to find and should be searchable from the repo landing page.

[smiths]

Our preferred landing page is a good decision to make explicit. I often point people to Drasil (over informal e-mails, publications, presentations, grant applications etc.). I always point to the regular GitHub page:

https://github.com/JacquesCarette/Drasil

We may decide to instead direct people the GitHub.io page:

https://jacquescarette.github.io/Drasil/

I'm fine with either. I'm not 100% convinced that the GitHub.io page is the usual default for other projects, but maybe that is because these pages GitHub.io pages are a newer thing and I'm just used to the original way we did things. :smile:

I think once the purpose and audience of each page is determined, the useful content should follow relatively straightforwardly.

[JacquesCarette]

Drasil - website design