Format Key Points - Githubissues

ashander commented 7 years ago

These are not currently formatted in any of the episodes. If there are none, delete the box

[x] 00-sql-introduction.md
[x] 01-sql-basic-queries.md
[x] 02-sql-aggregation.md
[x] 03-sql-joins-aliases.md

orchid00 commented 7 years ago

Not so sure what the issue is

tpoisot commented 7 years ago

Me neither.

ashander commented 7 years ago

The new template has a 'Key Points' box at the end of each lesson. Currently these are empty, e.g. in Lesson 00

orchid00 commented 7 years ago

OK, this is likely to be part of the template. Would you like to add some key points as a PR?

bsmith89 commented 7 years ago

I'll take this for 00-sql-introduction.md.

bsmith89 commented 7 years ago

For my own reference: key points are added to the YAML header of the .md file for the episode like so:

---
title: "Formatting"
teaching: 10
exercises: 0
questions:
- "How are Software and Data Carpentry lessons formatted?"
objectives:
- "Explain the header of each episode."
- "Explain the overall structure of each episode."
- "Explain why blockquotes are used to format parts of episodes."
- "Explain the use of code blocks in episodes."
keypoints:
- "Lesson episodes are stored in _episodes/dd-subject.md."
- "Each episode's title must include a title, time estimates, motivating questions, lesson objectives, and key points."
- "Episodes should not use sub-headings or HTML layout."
- "Code blocks can have the source, regular output, or error class."
- "Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier."
- "Special sections may be callouts or challenges; other styles are used by the template itself."
---

ashander commented 7 years ago

Helpful stuff for anyone else working on this too. Thanks!

On Fri, Apr 7, 2017 at 10:58 AM, Byron Smith notifications@github.com wrote:

For my own reference: key points are added to the YAML header of the .md file for the episode like so:

title: "Formatting" teaching: 10 exercises: 0 questions:

"How are Software and Data Carpentry lessons formatted?" objectives:

"Explain the header of each episode."

"Explain the overall structure of each episode."

"Explain why blockquotes are used to format parts of episodes."

"Explain the use of code blocks in episodes." keypoints:

"Lesson episodes are stored in _episodes/dd-subject.md."

"Each episode's title must include a title, time estimates, motivating questions, lesson objectives, and key points."

"Episodes should not use sub-headings or HTML layout."

"Code blocks can have the source, regular output, or error class."

"Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier."

"Special sections may be callouts or challenges; other styles are used by the template itself."

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/datacarpentry/sql-ecology-lesson/issues/129#issuecomment-292608092, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfLOB02pr6X5ys17s7GtLfrCbq7aMQEks5rtnlMgaJpZM4MgAUS .

bsmith89 commented 7 years ago

It would appear that other DC lessons also don't have Key Points sections. Is this something that should be changed?

ashander commented 7 years ago

There are probably existing issues/PRs flagging this in appropriate repos.

I know they're being added / have been added in at least one case: https://github.com/datacarpentry/spreadsheet-ecology-lesson/pull/126

On Fri, Apr 7, 2017 at 11:12 AM, Byron Smith notifications@github.com wrote:

It would appear that other DC lessons also don't have Key Points sections. Is this something that should be changed?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/datacarpentry/sql-ecology-lesson/issues/129#issuecomment-292611452, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfLOAR_F1G2k05dfLsJ36cFsF6aKVMbks5rtnx7gaJpZM4MgAUS .

ashander commented 7 years ago

ps @bsmith89 please update here if you are taking this on for more than just lesson 00 (no pressure ;). if so I'll update the checklist above accordingly

ASGeorge commented 7 years ago

Good day. Working on adding key points for 01-sql-basic-queries.md.

bsmith89 commented 7 years ago

Will do.

Also, again for my own reference (sorry if this is getting spammy), here is an example from swcarpentry/python-novice-gapminder Episode 7:

keypoints:
- "Use the Pandas library to do statistics on tabular data."
- "Use `index_col` to specify that a column's values should be used as row headings."
- "Use `DataFrame.info` to find out more about a dataframe."
- "The `DataFrame.columns` variable stores information about the dataframe's columns."
- "Use `DataFrame.T` to transpose a dataframe."
- "Use `DataFrame.describe` to get summary statistics about data."

bsmith89 commented 7 years ago

Releasing 00-sql-introduction.md.

Claiming 02-sql-aggregation.md.

bsmith89 commented 7 years ago

Done (for now) contributing to 02-sql-aggregation.md.

ashander commented 7 years ago

I'll add some for 03-sql-joins-aliases/

bsmith89 commented 7 years ago

The choice of key points look really good (IMO) in #157, #161, #162, and #165.

One thing maybe worth considering is that the voice we've used is inconsistent across the four episodes. This is also the case across Carpentries lessons, e.g. SWC-shell-episode2 vs. SWC-python-gapminder-episode7

Is it worth thinking about a "style guide" for these key points, either within this lesson or more globally?

ashander commented 7 years ago

good point @bsmith89 I'm not sure we could or should take on the broader issue here, but it's good to flag it. for the issue of consistency across our PRs, what specifically do you mean? I've merged everything and pasted a combined diff below for easy reference. Differences I see:

some of the points are pithier and some more verbose. (I'd favor pithier while possible)
use of `` around commands/keywords

_episodes/00-sql-introduction.md:

```sh index bab2d21..bdb3a35 100644 --- a/_episodes/00-sql-introduction.md +++ b/_episodes/00-sql-introduction.md @@ -8,6 +8,10 @@ questions: objectives: - "Understand the benefits of using a relational database" - "Set up a small database using SQLite" +keypoints: +- "SQL allows us to select and group subsets of data, do math and other calculations, and combine data." +- "A relational database is made up of tables which are related to each other by shared keys." +- "Different database management systems (DBMS) use slightly different vocabulary, but they are all based on the same ideas." --- ## Learning Objectives ```

_episodes/01-sql-basic-queries.md:

```sh index 9be5b23..0034ace 100644 --- a/_episodes/01-sql-basic-queries.md +++ b/_episodes/01-sql-basic-queries.md @@ -8,6 +8,11 @@ objectives: - "Write and build queries." - "Filter data given various criteria." - "Sort the results of a query." +keypoints: +- "It is useful to apply conventions when writing SQL queries to aid readability." +- "Use logical connectors such as AND or OR to create more complex queries." +- "Calculations using mathematical symbols can also be performed on SQL queries." +- "Adding comments in SQL helps keep complex queries understandable." --- ## Learning objectives ```

_episodes/02-sql-aggregation.md:

```sh index 2a5d039..c3514be 100644 --- a/_episodes/02-sql-aggregation.md +++ b/_episodes/02-sql-aggregation.md @@ -9,6 +9,11 @@ objectives: - "Filter and order results of a query based on aggregate functions." - "Save a query to make a new table." - "Apply filters to find missing values in SQL." +keypoints: +- "Use the `GROUP BY` keyword to aggregate data." +- "Functions like `MIN`, `MAX`, `AVERAGE`, `SUM`, `COUNT`, etc. operate on aggregated data." +- "Use the `HAVING` keyword to filter on aggregate properties." +- "Use a `VIEW` to save a query as though it were a new table." --- ## Learning Objectives ```

_episodes/03-sql-joins-aliases.md:

```sh index 34b2c45..29a6368 100644 --- a/_episodes/03-sql-joins-aliases.md +++ b/_episodes/03-sql-joins-aliases.md @@ -8,6 +8,13 @@ objectives: - "Employ joins to combine data from two tables." - "Apply functions to manipulate individual values." - "Employ aliases to assign new names to items in a query." +keypoints: +- "Use the `JOIN` command and `ON` or `USING` keywords to combine data from two tables." +- "Regular `JOIN` returns only matching rows. Other join commands provide different behavior, e.g., `LEFT JOIN` retains all rows of the table on the left side of the command." +- "`IFNULL` allows you to specify a value to use in place of `NULL`, which can help in joins" +- "`NULLIF` can be used to replace certain values with `NULL` in results" +- "Many other functions like `IFNULL` and `NULLIF` can operate on individual values." +- "Aliases can help shorten long queries. To write clear and readible queries, use the `AS` keyword when creating aliases." --- ## Learning Objectives ```

bsmith89 commented 7 years ago

pithier vs. verbose is the most obvious one
choices about at what level details should be combined into a single point versus split up
scope of key-points: should they be limited to details of using SQL, or does conceptual stuff belong, too.

tracykteal commented 7 years ago

Thanks for the idea of the style guide for 'key points'. This is a good broader discussion. I created an issue in the lesson templates repository. https://github.com/swcarpentry/lesson-example/issues/112

datacarpentry / sql-ecology-lesson

Format Key Points #129

"Special sections may be callouts or challenges; other styles are used by the template itself."

_episodes/00-sql-introduction.md:

_episodes/01-sql-basic-queries.md:

_episodes/02-sql-aggregation.md:

_episodes/03-sql-joins-aliases.md: