Drasil
Drasil copied to clipboard
JacquesCarette
Improve Drasil Website
Although issue #1599 can be closed because the feedback from when that issue was created has been addressed, a discussion of the website during meeting #3038 highlighted that a more thorough review of the Drasil website is in order. Therefore, I've created this issue.
To start with, we need to identify the audience for our website and the purpose that it serves. In the short term the website is principally for students that are joining the Drasil project. In the future, we hope to attract developers at other institutions that can contribute to developing Drasil. Although not ready yet, we also hope to attract users of Drasil. That is, people that will use Drasil in their scientific/engineering projects, without necessarily trying to expand the functionality of Drasil.
For the future goals (attracting developers and users), we need to make sure that the website quickly conveys the purpose and benefits of Drasil. We need to "sell" Drasil.
Some specific ideas/steps, as captured by @peter-michalski include the following:
- @peter-michalski will review the Wiki for any items that should be added to the website (we can then discuss those ideas in this issue thread.)
- Add information on getting started with Drasil. We have a quick start, but a more detailed getting started would help future students
- Explicitly list the artifacts we currently create (SRS, code (in various languages), Makefile, README, etc.)
- Explicit list of artifacts we hope to generate in the future. This can be part of a product roadmap.
- Look at the common contents of README files, as summarized in the PranaEtAl paper, to see what we may be missing
- Look at the knowledge that Olu has identified in other GitHub projects and SE textbooks to see what we may be missing
- Promote Drasil by quantifying the number of artifacts that it can produce
- Add information to encourage people to help develop Drasil (and use Drasil). To do this, we can look at the following resources:
- Review the artifacts listed in Table 3 of the Digging Deeper paper to see which ones we are missing from our website/repo.
- Look at the advice for growing the number of contributors in Section 10.4 of the SOP for LBM paper to see if there are any artifacts we should add to our website.
- Consider adding an introductory blurb that explains Drasil in plain language (Before the current into? Move current intro to another section? As an abstract?)
- As proposed by @cd155, clarify some of the overly academic terminology, like artifact, generation, traceability, etc.
- Ask future students to critically evaluate the website and provide us with feedback and advice
@balacij and @cd155, please edit the above to clarify any of the points and to add any points that @peter-michalski and I may have missed from our conversation.
Other parts of the Wiki that we may want to consider adding information from (or linking directly to the Wiki page - we should have at least one link to the main Wiki page):
- Information Encoding - at least a blurb that will serve as a precursor to an introduction of chunks
- Chunks - intro and structure; lead the reader into recipes
- Recipes - intro blurb (recipes are already mentioned on the website, so we may want to rearrange the current content to begin with information encoding and chunks)
- A blurb about GOOL
- Add a link to Drasil papers
I don't think that this (along with the points in the opening comments) would be too much information to add to the website, but I'm reluctant to add more on a single page.
Below is a WIP proposed structure for the webpage:
Introduction - new introduction
- An elevator pitch, primarily aimed at students and collaborators, explaining Drasil in plain language
Getting Started
- Quick Start Guide
- Navigate to the Quick Start Guide to see what Drasil can do.
- New Workspace Setup
- Workspace recommendations are available in the New Workspace Setup page
- Contributor's Guide and Workflow
- If you are interested in contributing to the project, please look at the Contributor's Guide, as well as the Workflow page
- Creating Your Own Project
- If you are interested in creating your own project in Drasil, please look at the Creating Your Project in Drasil page
- Debugging Drasil
- Debugging information can be found in the Debugging in Drasil page
About - former Introduction old introduction content + the following subsections (review Olu's work for potential additions):
- artifacts we currently generate
- SRS
- code
- README
- Makefile
- artifacts we hope to generate (including review of Digging Deeper paper, and SOP for LBM paper)
- License
- Installation Instructions
- Dependency List
- Authors
- Getting Started / User Manual
- Release Info
- Design Documentation
- Build Scripts
- Test Cases
- information encoding
- As described in the Information Encoding wiki page, Drasil uses specific terminology to address types of knowledge for the purpose of encoding information, since we know that we want to eventually generate words, sentences, paragraphs, whole documents with headings, references, formulas, tables, graphs, and code. This is done by trying to understand the basic 'units' of all artifacts, and methods for composing larger structures from these units. The removal of duplicate units is an important feature of this methodology. The basic building blocks of the methodology include different expressions for units with a specific meaning. These are built into ontologies of domains that address broader knowledge. Chunks form a fundamental part of such ontologies.
- chunks
- As described in the Chunks wiki page, a chunk is a data type specialized in holding a specific type of information for a specific purpose so that knowledge may be used in generated models, definitions, and theories. Chunks are usually made up of several lower-level types that hold lower-lever information; when contained together, these pieces of lower-level information hold a new specific purpose. The structure of a chunk can be thought of as a wrapper of information, and this is all implemented using Haskell's record-type syntax. Recipes transform the acquired knowledge into a usable format.
- recipes
- As described in the Recipes wiki page, recipes are instructions that unpackage necessary information from chunks and send that information to Drasil generators/printers to build complete artifacts. When an artifact needs to be changed, the recipe is modified to unpackage the additional necessary information from a chunk, or alternatively to omit unpackaging information that is no longer required.
- GOOL
- As described in the GOOL paper, this is a Generic Object-Oriented Language that provides intermediary assistance in code generation, allowing Drasil to more efficiently generate code in several languages, including Python, Java, C#, and C++.
- Drasil papers
- A list of papers and documents written about Drasil can be found in the Drasil Papers and Documents wiki page
Generated Examples
Case Studies
Haddock Documentation
Analysis of Drasil
Academic terminology should be clarified as needed
Great start to the outline @peter-michalski. Thank you for driving this forward. I have a few quick notes:
- We generate other things besides the SRS, including code, README files and makefiles.
- We should probably make the introduction shorter. We can just hit the main points of what Drasil is hoping to do. The more detailed information could be moved after "Getting Started." Most web-pages quickly get to getting started, probably because users don't have any patience.
2. Most web-pages quickly get to getting started, probably because users don't have any patience.
Good point @smiths . I have applied your notes to the outline comment.
- Add information on getting started with Drasil. We have a quick start, but a more detailed getting started would help future students
For the sake of avoiding duplication of information, I have chosen to mostly add links on this page to the relevant GitHub wiki pages. Consequently, it may be appropriate to review and edit the current quick start page on GitHub.
7020a821289ce07bb7b520b6ea2f7c4b7300e8ca contains the updated website code
I don't really want to close this issue quite yet, it has too much valuable information on it. Maybe when we're done with #3067 (as an issue, not as a task), we can also close this?
