Skip to content

Commit

Permalink
adding md ide
Browse files Browse the repository at this point in the history
  • Loading branch information
librarianrafia committed Dec 14, 2023
1 parent a57a9cf commit 7f09d6e
Show file tree
Hide file tree
Showing 3 changed files with 12 additions and 57 deletions.
3 changes: 2 additions & 1 deletion docs/ide.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# IDE

# **integrated development environment (IDE)**
**integrated development environment (IDE)**
* An IDE is a computer program that helps in writing and working on software. It allows you to create files such as .md (Markdown), .py Python, .r (R), etc. An IDE is only needed if we are going to create a Markdown file in the workshop
- In the content for this workshop, the examples use Visual Studio Code/
- [Visual Studio Code](https://github.com/DHRI-Curriculum/install/blob/v2.0/guides/visual-studio-code.md) (recommended) You can use any plain text editor but for our purposes, Visual Studio Code ("VS Code") will be used.
Expand Down
58 changes: 6 additions & 52 deletions docs/markdown.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
[<<< Previous](pedagogy.md) | [Next >>>](contributing.md)
# Markdown

# Style Guide

**See Checklist for Required Content (ADD LINK)**

## Why use Github?
* *link to lesson* etc add text
[Github at SMU](https://www.smu.edu/OIT/Services/GitHub)
[The Markdown Guide is a free and open-source reference guide that explains how to use Markdown, the simple and easy-to-use markup language you can use to format virtually any document.] (https://www.markdownguide.org/)

## Why use Markdown?

Expand Down Expand Up @@ -43,7 +37,7 @@ When rendered by a browser, both of these documents look identical. However, the

### Why Use Markdown?

We use markdown for tutorials for a number of reasons:
Markdown is used for a number of reasons:

- It's exportable to other formats, such as HTML, PDF, and GitBook.
- It can be kept under version control—with Git, for example.
Expand All @@ -59,6 +53,8 @@ Many of markdown's advantages come from the fact that it's plain text. Tools tha

Most formatting guidelines here are designed to make markdown source files more readable. Others are designed to preserve semantics, which allow markdown to be rendered the same in different contexts.

Here are some example guidelines.

* Formatting should be as follows:
1. Separated paragraphs with a blank line.
2. Place blank lines between elements whenever possible. For example, put a blank line between a heading and a paragraph, and between a paragraph and an image link.
Expand All @@ -75,52 +71,10 @@ Most formatting guidelines here are designed to make markdown source files more
* Are there any extraneous Markdown tags due to errors in coding? (hashtags, dashes, etc.)
* [Basic Syntax](https://www.markdownguide.org/basic-syntax/)
4. Use other markdown elements for their intended purpose. Use lists for lists and emphasis for emphasis. For example, do not use emphasis in place of a heading.
5. Unless a raw URL is part of the tutorial, don't leave raw URLs in your document. Incorporate the link into the flow of your prose.
5. Unless a raw URL is part of the document, don't leave raw URLs in your document. Incorporate the link into the flow of your prose.
6. If code segments are short, indicate them by indenting. If they're longer, use the ````` syntax.
* Is coding consistent throughout module?
7. When introducing new commands or code, put them on a new line so they stand out from the rest of the text.
8. When including [including images,](https://www.markdownguide.org/basic-syntax/#images-1) don't leave the alt text segment `[]` blank. Fill it in with information that would be useful if the image could not be seen or rendered.
9. ANYTHING ELSE? do images need to go into image folder? sections into a folder? after certain amount ? (otherwise need to scroll waaaaay down README)



# Jupyter book?
* RULES?
* To be used when:
- combining multiple workshops
- maintained by multiple instructors
- into a sequence (Research Workshop Path)
* See example: Repo-[Introduction to TDM](https://github.com/SouthernMethodistUniversity/introTDM) & JB- [IntroTDM](https://southernmethodistuniversity.github.io/introTDM/index.html)

# When to choose Binder or HPC for computational documents
* RULES?
* To be used when:
- combining multiple computational notebooks
- Introductory workshops where familiarity with HPC is not assumed (or required)
* See example: [Python Repo](https://github.com/SouthernMethodistUniversity/pythonintro)

# Accessability
* * **HERE..link to accessibility style guide??**
* write accessible documentation (https://developers.google.com/style/accessibility)
* For example do not emphasize text by using color
[A markdown version emoji cheat sheet](https://github.com/ikatyang/emoji-cheat-sheet). You can call attention using a [geometric icons](https://github.com/ikatyang/emoji-cheat-sheet#geometric) such as :red_circle: or :yellow_circle:

# Attribution
## Free and Open Source Code

In general, it's not necessary to provide in-line citations in the materials for a technical workshop unless you're using someone else's exact prose or you're replicating a significant, non-trivial section of code. For example, code segments found on Stack Overflow do not need to be cited unless you think it's pedagogically helpful. However, if you build your session around replicating a significant portion of a particular application, you must consider the license under which that software is released and consider providing attribution, even if attribution is not required under the terms of the license. In general, free and open source code licenses do not require attribution, but using a large portion of the code may require replicating the license. Check a summary of the terms of the license (or the license itself, if you're feeling adventurous) if you decide to replicate a significant portion of an open-source project in your session.

## Citation practices for workshops

Many of the workshops in this curriculum were created by multiple creators. This makes the process of attributing of each other a bit messy. An interested person can see the precise details what was done and by whom in what order in the GitHub commit log. However, we also realize that folks reading this curriculum may not be Git-literate (yet!) or may access this curriculum as a .PDF or a hard copy document offline. Thus, it is also important to attribute the labor of individual contributors in written form at the beginning of each workshop and every other section of this curriculum.

Currently, the workshops include two forms of attribution: "Session leader: ..." and "Based on previous work by ..."—the former indicates the person who will be the lead teacher of the workshop during the Summer 2020 DHRI session, and the latter indicates who worked on the content of the workshop. We recognize that both are significant attributions, but that the latter is especially important in terms of citation politics, particularly for students and junior scholars. So, despite its redundancy, we listed a contributors name twice if they both are leading the workshop in June 2018 and if they created or significantly contributed to or revised the workshop's content. It is also of note that various contributors edited the content of each others' workshops.

In regards to citing other academics, this curriculum aims to follow commonly held academic citation practices, in which direct quotations are formatted and cited as such, and when another scholar's ideas or concepts are referenced, a citation is also included. In general, the following citation information is provided: the author name(s), publication title, and publication date, and a hyperlink to the source, if applicable and within copyright.

## License?
- Default to CC by SA? discuss



[<<< Previous](pedagogy.md) | [Next >>>](contributing.md)
8 changes: 4 additions & 4 deletions docs/whycoding.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Why Learn Coding (Optional)
* This section is to give context to
# Why Learn Coding

# Computing
Understanding computing: This section is to familiarize you wth important foundational concepts and to give you a framework for understanding the types of computational methods you can use on a projects, including: minimal computing, tool choice or coding. Finally, this session aims to give you language to conceptualize what is possible and to communicate more effectively with partners.
* This section is to give context to:

* Understanding computing: This section is to familiarize you wth important foundational concepts and to give you a framework for understanding the types of computational methods you can use on a projects, including: minimal computing, tool choice or coding. Finally, this session aims to give you language to conceptualize what is possible and to communicate more effectively with partners.

* Understanding the affordances and limitations of a computational approach for your project will help you better imagine, plan manage your project. Even if you are not directly involved in the coding aspect, this will give you the tools to better collaborate with those who will.

Expand Down

0 comments on commit 7f09d6e

Please sign in to comment.