dhri-curriculum / html-css Goto Github PK

Send to Kalle (via Slack):

1. A headshot—make sure it is recent and as high-resolution as possible (if you have questions, feel free to reach out!).

2. A bio—max 150 words.

3. Any number of links to current websites and projects you have worked on and want to display.

4. A "Meet your instructor" blurb (keep it short, less than 200 words) about why you got involved/how you have had use of the tool(s) that are introduced in your workshop.

   For this part, think about how you build trust and report with participants in digital research institute. Since we cannot build that if we don't meet participants in-person, how would you come up with language (narrative/rhetorical strategies) to provide a surrogate for this face-to-face interaction?

something like this guide @smythp created would be great to add into that images.md section:
https://github.com/smythp/github-images-test

lessons.md

• Accept any pending pull requests

• Implement all the edits/requests that you have left from your colleagues (Di's comments, and Stefano's comments on lessons, theory-to-practice, assessment, and frontmatter)

• Add any additional content you think is needed for version 2.0 _and open any other using the label in your repo

• Ensure the length of each lesson is not too long
  each section (beginning with a level 1 heading [#]) should be no more than 3-4 paragraphs

• Ensure temporal references and references to other workshops are removed (since learners will “attend” these workshops mostly asynchronously)

frontmatter.md

• Finalize and streamline all sections

• Ensure your abstract is no longer than ~100 words
  If you need/want them to be longer, you can create a new first section in lessons.md and put the longer version of the abstract there.

• Resolve any "TBD" content.

• Make sure collaborator lists are complete with roles and links
  see Di’s example but feel free to add links to people’s websites!

• Ensure all Projects and Readings have "annotations"
  annotations = 1-2 sentences answering “Why is it important for our learners to read or expose themselves to these readings/projects”? For examples, see agenda doc

theory-to-practice.md

• Finalize and streamline all sections

• Resolve any "TBD" content.

• Ensure all Projects, Readings, and Tutorials have "annotations"
  annotations = 1-2 sentences answering “Why is it important for our learners to read or expose themselves to these readings/projects”? For examples, see agenda doc

In Sprint 2, once again, we need your help moving content over from the old format into a new format. This time around we will do so in two steps:

1. Copy-paste of content
   It doesn't sound very fun but it will be rewarding to go over the material once again and review the flow from one lesson to another.

   • Create a file lessons.md in the root of your repository. This will be the home of the entire lesson-flow.

   • For each of the lessons in the sections directory in your repository:

     • Remove any lines that contain "navigation bars" (eg. <<< Previous Next >>>)
     • Ensure that the first header is of level 1 (# ) and any following headers are level 2 (## ), and if there are nested headers under that, that they are consequential with the previous ones.
     • Once you've done that, copy the text from the section file, and
     • Paste the contents after the end of the lessons.md file.

2. Once you have the whole flow set up in the lessons.md file, it is time to begin looking over the style and content of the entire body of the workshop:

   • Ensure that any multi-line code blocks are correctly encased in three after one another—```— feel free to also annotate whether the code is python, html, css or anything else by adding those terms after the triple backticks. (You can read more about this technique here)

     ` ` `css
     testing out code
     ` ` `

     (In this example I have used spaces between the backticks because otherwise the block would not render correctly here, so keep the backticks with no spaces in your real-world work.)

   • Inline code, commands, filenames, or keyboard shortcuts should also be surrounded by single backticks:

     As you can see above, the `=` sign lets you assign symbols like `x` and `y` to data.

     (This example comes from the python workshop. You can see it in action here)

   • Feel free to use bolding (**bolded**) and italicizing (_italicized_) where you see fit, but sparingly. If it clarifies your content, good. Just remember that they can be overwhelming.

   • Try to make sure each section ends with a question/challenge/problem that makes our learners act and think on their own. Here's how the formatting should look (keep the ## Challenge header even if yours isn't technically a "challenge"):

     ## Challenge
     
     Here is where I write the challenge as a regular paragraph.
     
     ## Solution
     
     Here is where I write the solution as a regular paragraph.
     
     ` ` `python
     print("In the challenge and/or the solution, you can, of course, use code blocks and styling too!")
     ` ` `

   You can see an example in the python workshop, and you can see what it will look like in production—albeit still very much under development at the end of this page.

   • Pay attention to images that are, or should be, present. Do you need more/newer screenshots? Are the existing ones too old, of a low resolution, blurry, unclear? Please provide (i.e. upload screenshots with clear names) in an images directory that you can create in the repository's root directory. Link them in your lessons.md file by using markdown:

     ![don't forget to describe your image for the alt text here](images/your-image-name.png)

   • As above, pay attention to where you think an animated gif or a screencast might be appropriate, and make a note of it in the text. You can either put a placeholder, or a comment using inline html comments:

     <!-- it would be good with a screencast/gif here -->

   • If you find images that have been borrowed from elsewhere and credits are missing, please try to make sure we have appropriate credits in the text inline, or immediately after the image. (Pro-tip: You can use Google image search to find sources for most files.)

Resources

Style example

lessons.md example from project-lab

I wonder if it makes sense to mention Wordpress somewhere in the frontmatter file. It's my understanding that it would help folks connect the kind of work done in the workshop with a platform that they might be familiar with. If so, I think it would make sense to have it either in the opening blurb or in the "Projects that use these skills" section.

Also, in Ethical considerations, we may want to add a link to thee WAVE Tool https://wave.webaim.org/ so folks can see firsthand what an accessible website entails (and how many high profile websites that seem to be accessible, are not THAT accessible!). Maybe also explain what screen readers are?

At this point, the lessons.md file should be complete enough that you will be able to go through each lesson and come up with (at least) one evaluative question per lesson, on what the learner should have picked up from the lesson. They should be expressed in the form of multiple-choice questions, with one or more correct answers.

How to add a multiple-choice question

Go through the lessons.md file, and for each lesson, create a new section at the end (## Evaluation) where you will add the question and each of the answers, marking the correct ones with a * at the end of it. (See an example here.)

Optional: Add open-ended questions

If you want to, in addition to the multiple-choice evaluative question, you can also raise an open-ended question, expressed as “Do you think you can answer this question:” As there is no easy way to programmatically understand the input in a text field to such a question (although, of course, not impossible), we will not be able to build such a functionality into the website. But we can offer open-ended questions as a feature for the learners to think further about the workshop’s contents. Perhaps they can be about an ethical aspect of the lesson?

Unfortunately, they often are, but, at least according to universal design principles, they shouldn't be. If images are conveying crucial information, then the site isn't accessible.

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a assessment.md file in the root directory of your repository
  Here, you can find the template for assessment.md. Copy the contents into the new file in your repository.

• Complete the quantitative self-assessment section

  • Use ## Quantitative Self-Assessment to indicate the beginning of the section.

  • Move all the relevant quantitative self-assessment questions from DHRI/DRI exit slips found in the GCDI Google Drive over to this file.

  • Each question should be a regular paragraph.

  • Each question should have multiple choice answers, added as bullet points under the paragraph (in markdown, you use - on a new line to create a bullet point).

  • Make sure that the questions enable the learner to evaluate their understanding of specific concepts from the workshop.

• Complete the qualitative self-assessment section

  • Use ## Qualitative Self-Assessment to indicate the beginning of the section.

  • Move all the relevant qualitative self-assessment questions from DHRI/DRI exit slips found in the GCDI Google Drive over to this file.

  • Each question should be a regular paragraph.

  • For each question, think of readings/tutorials/projects/challenges from the "Theory to Practice" section to direct them to, and add a note of that as a bullet point under relevant questions (in markdown, you use - on a new line to create a bullet point).

  • Make sure that the questions enable the learner to evaluate their understanding of specific concepts from the workshop.

Left TBD from sprint 1, see #43.

@smythp i'm making my edits to the curriculum html/css repo now, and when i refresh the page, i'm not seeing the edits. Is this because you need to review and accept them (according to github)? I just want to make sure I'm doing this correctly.

@smythp it looks like you changed the examples I was using for the index.html file. was there a reason for doing that? i sort of think something similar might be better, but i'm open to being persuaded.

A few random comments:

1. This echoes the comment I left for the frontmatter section: we may want to mention CMSs much earlier in the workshop, rather than just drop a link at the end. This is one of those instances where, if we were to hold a workshop in person, we'd just showcase a WordPress site and show the participants how much work WRITING an actual site a CMS does (I think @hackettka used to do this in her workshop?), but since we can't do that in this new format, maybe we want to add a few lines in the lessons file on this? I think it would really help folks understand that they don't NEED to write a whole site in HTML from head to toe if they want to build a website!

2. Similarly, I see that we list Omeka, WP, and GitHub in the "Projects to Try" section, it also comes out as a bit abrupt here, since we don't mention (or maybe we do, and I missed it?) any of those platforms earlier in the workshop?

3. Among the suggested reading,we may want to add something on webdeveloping itself? Maybe a checklist such as this -- Not the ideal source, I know -- or a list of web designing best practices? So much of what we take for granted may need to be spelled out to beginners!

Yes, OSX users need to be told this every time. :(

Feel free to close this issue after you have pushed all of your local branch updates to your GitHub repo, so I can initiate a pull request to the v2.0 branch. (If you feel comfortable and interested in doing it yourself, you can do that as well, of course!)

This is the issue that closes out the v2.0 edits from you. Thank you so very much for all your hard work this summer!

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a frontmatter.md file in your repository
  Here, you can find the template for frontmatter.md. Copy the contents into a new file in your repository.

• Finish the Abstract section
  Transfer over relevant portions from readme.md into the ## Abstract section in the frontmatter.md file.

• Finish the Learning Objectives section
  Transfer over relevant portions from readme.md into the ## Learning Objectives section in the frontmatter.md file.

• Check this one for free: the Estimated Time section
  Leave the ## Estimated Time section in the frontmatter.md file as it is (we will come back to this during our testing period).

• Finish the Prerequisites section
  Think of prerequisites that will be important for learners to know in advance of this workshop that should go into the ## Prerequisites section in the frontmatter.md file.

• Finish the Pre-reading suggestions section
  Think of/search for reading suggestions that could be good for learners to have read in advance of this workshop that should go into the ### Pre-reading suggestions section in the frontmatter.md file.

• Finish the Projects that use these skills section
  Think of/search for projects that you know, which could be good for learners to look at in advance of this workshop that should go into the ### Projects that use these skills section in the frontmatter.md file.

• Finish the Ethical Considerations section
  Think of ethical quandaries that could be good for learners to consider in advance of this workshop that should go into the ### Ethical Considerations section in the frontmatter.md file.

• Finish the Resources section
  List any required installations, shortcut sheets, or other resources that can be helpful for learners to take care of/look at in advance of this workshop and add them into the ### Resources (optional) section in the frontmatter.md file.

• Finish the Acknowledgements section
  List all the full names of every person who have worked on and contributed to this repository over the years in the ## Acknowledgements section in the frontmatter.md file. Each person should be added as a bullet point list.

Maybe a description of what they're seeing and another screenshot? If people are teaching from this, they might well wonder themselves what they're supposed to bw seeing.

Ok, last issue for today.

1. In the opening activity, where we show folks how to access a webpage source – is there any way to do this with I.E. or Edge?

2. I think it makes sense to explain what XML and XHTML are, or at least add a link to them? Again, this is one of those things we would just mention in passing in an in person workshop, and we may need to be super-specific and more careful in spelling things out in this new format.

3. I wonder if it makes more sense to break down those challenges into smaller/scaffolding ones + add solutions (maybe in the form of a screenshot AND either a txt file with the code or embedding the code in the page?)

4. The "Additional Tags" subsection shouldn't be a subsection of a challenge, according to the templates. Correct? @kallewesterling

@smythp i don't have the option to close out issues in the github web interface. from what I'm seeing online, this may be because I'm not a 'collaborator' on the project.. ? maybe this is the deal with the other issue?

This is just a note to make this uniform throughout. Most of the workshop spells out CSS as "cascading stylesheets" but then the readme refers to it as "Cascading Style Sheets" (the latter makes a bit more sense for remembering the acronym).

I reference sublime as an example of a text editor consistently, but this should be changed to whatever we end up using.

They always want to make navbars, might add some code on that.

Maybe think of some questions to add/re-articulate? e.g., Qualitative: What are the pros and cons of integrating CSS inline, internally, and externally? When and why would you use each?

e.g., Quantitative: How confident were you about using HTML/building a website before this workshop?

What I did with mine was shape it after Lisa's.

Just a reminder to add a resources page

Also, to include on that page, Hannah suggested this guide to HTML on Mozilla:
https://developer.mozilla.org/en-US/docs/Web/HTML

There's also another guide to CSS on Mozilla:
https://developer.mozilla.org/en-US/docs/Web/CSS

It would be good if you / someone could also find a source that discusses universal design or design for folks for physical disabilities that addresses HTML and/or CSS

I can't seem to get my images to show up properly in my lessons.md file. I'm not sure if this is an issue with github or with the way in which I am doing the images. Need to learn more about images and markdown and properly linking to images.

The current "making your website public" section doesn't provide enough concrete information on how to actually put a website on the internet. It abstractly discusses FTP and web hosting, without providing step-by-step instructions to make a website public. Some suggestions / thoughts on improving this section:

1. Include more information on content management systems like wordpress, scalar, and omeka. This can be a way of learning-by-doing, and it can give people confidence in putting up a website.
2. Include a robust overview of reclaim hosting. This can teach people how to buy a domain name and use a virtual server.
3. Include an assignment on using StoryMaps. This can help bring together the lessons on GIS and website development.

• Go through lessons.md (and other files) and find all important terms in need of definition to help learners grasp concepts, tools, commands, etc. List the files in a text file, or keep them in this issue feed below, for instance.

• Add a file to the glossary repository's terms folder called <term>.md for each of the terms.

  • How do I add terms to the glossary? <— See instructions

We want to make sure that the theory-to-practice.md file is somewhat more useful welcoming than only a couple of bulletpoints, so this feature request concerns the end of your workshop.

Imagine the theory-to-practice.md file as a form of mentoring and consultation (or a step in that direction): What would you say at the end of your workshop to help think about how the skill the just learned could be refined and improved? Can you give the learner something more to go on than a bulleted list? Something that would entice them to stay on this page and choose to dig deeper into the skills/tools in your workshop?

Concrete step

Add one or more regular paragraph/s at the top of your theory-to-practice.md file (under the line that contains # Theory to Practice and before ## Suggested Further Readings). If you need, use formatting (** for bolding and _ for italics), and/or headings (but make sure to only use level 3 headings—###).

You can see an example here. If you have any questions, don't hesitate to tag @kallewesterling and comment below, or DM via Slack.

• Look at your workshop on the website to see what your workshop currently looks like, and what looks like it needs to change.
• Think about order and transitions—do the lessons follow a logical pattern and is it working? Do you need to add something somewhere? Are the transitions between the lessons clear?
• Can you add a challenge at the end of the lesson that summarizes what the learner has learned, and activates the knowledge in an interactive way.
• Think about the length of the lessons — are they too long? Too short? In general, each lesson should cover one topic, or one particular skill — or perhaps connect two skills. If you find that you’re covering more than that in one lesson, perhaps they should be split into more than one.
• While reviewing the lessons.md file, think about vocabulary terms that we should add in an easily accessible "dictionary" for our learners.

Feel free to reach out to me and @lmrhody and ask for help, if you need it. Also feel free to involve others in the group!

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a theory-to-practice.md file in your repository
  Here, you can find the template for theory-to-practice.md. Copy the contents into a new file in your repository.

• Add suggested further readings (optional)

  • Use ## Suggested Further Readings to indicate the beginning of the section, and bullet points for each of the sources (in markdown, you use - on a new line to create a bullet point).

  • If the reading has a DOI number, make sure to add it. If it does, you do not need to add any additional bibliographic information.

• Add other tutorials (optional)
  Use ## Other Tutorials to indicate the beginning of the section, and bullet points for each of the sources (in markdown, you use - on a new line to create a bullet point).

• Add projects or challenges to try (optional)
  Use ## Projects/Challenges To Try to indicate the beginning of the section, and bullet points for each of the projects/challenges (in markdown, you use - on a new line to create a bullet point).

• Add discussion questions (optional)
  Use ## Discussion Questions to indicate the beginning of the section, and bullet points for each of the questions (in markdown, you use - on a new line to create a bullet point).

I would love to have a "sequel" workshop to this one that explores platforms like omeka, humanities commons, etc. to imagine possible online digital humanities projects.

I'm not finding the tutorial very helpful when it comes to CSS. Specifically, it lost me at classes and IDs, on this page: https://github.com/DHRI-Curriculum/html-css/blob/master/sections/classes.md

My questions are just too numerous. What do ul and li stand for? What are they telling the computer to do? Are all these instructions for exterior styling or are some for interior styling? What even is a navbar? Do I already have one in my Institute website or are these commands telling me to add one? Can someone please explain anything about this code that I'm supposed to paste in (https://github.com/DHRI-Curriculum/html-css/blob/master/sections/navbar-hint.css)? Am I supposed to paste it in style.css or index.html? What is it supposed to look like if it's done correctly?