Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add syllabus docs #369

Merged
merged 44 commits into from
Sep 19, 2022
Merged
Changes from 1 commit
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
66f0996
Add syllabus docs
ErikSchierboom Jul 6, 2022
c3f3e3a
Draft introduction to syllabus design document
kytrinyx Aug 15, 2022
153846f
Tweak syllabus docs
kytrinyx Aug 15, 2022
1929f87
Add stub documents for syllabus-specific 'getting started' documents
ErikSchierboom Aug 16, 2022
b592ee8
Add some notes about first exercise in syllabus
ErikSchierboom Aug 16, 2022
52f8678
Add some notes about next exercises in syllabus
ErikSchierboom Aug 16, 2022
7b93abc
Add some notes about expanding exercises in syllabus
ErikSchierboom Aug 16, 2022
c529f30
Expand on building out the syllabus
kytrinyx Aug 17, 2022
d25afba
Flesh out syllabus docs
kytrinyx Aug 17, 2022
3931c94
Tweak syllabus docs
kytrinyx Aug 17, 2022
d7ce02b
Add note about creating issues to syllabus docs
kytrinyx Aug 18, 2022
e3fbb33
Update syllabus docs
kytrinyx Aug 30, 2022
258b4a1
Tweak wording on syllabus docs
kytrinyx Aug 30, 2022
7bce1ea
Tweak wording on syllabus docs
kytrinyx Aug 30, 2022
fa06929
Update syllabus docs
kytrinyx Aug 30, 2022
d66d32f
Add specifics about where and how to ask for help to syllabus docs
kytrinyx Sep 7, 2022
b908c38
Add a bit more about cyclic dependencies
kytrinyx Sep 7, 2022
6010970
Add a note about non-idiomatic code in syllabus docs
kytrinyx Sep 7, 2022
0cf5db7
Add spaces around emdash for readability
kytrinyx Sep 7, 2022
9e25304
Adjust initial goal explanation of first concept exercise
kytrinyx Sep 7, 2022
9856904
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
8736500
Add. missing spacing in syllabus docs
kytrinyx Sep 19, 2022
34a2ee0
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
7cfd5cd
Appease markdown linter in syllabus docs
kytrinyx Sep 19, 2022
c204316
Use more common form of gerund in syllabus docs
kytrinyx Sep 19, 2022
0a729f2
Use more common form of gerund in syllabus docs
kytrinyx Sep 19, 2022
2ab1502
Appease markdown linter in syllabus docs
kytrinyx Sep 19, 2022
c9825e8
Fix typo in syllabus docs
kytrinyx Sep 19, 2022
043046a
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
97b89f5
Change team name in syllabus docs
kytrinyx Sep 19, 2022
99c7565
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
b7f119a
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
4176c45
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
ef643ec
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
6930e41
Improve formatting in syllabus docs
kytrinyx Sep 19, 2022
3622c8c
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
c48692a
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
1e2ac24
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
9f62c7c
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
434f48d
Clarify syllabus docs
kytrinyx Sep 19, 2022
d646107
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
4708642
Improve wording in syllabus docs
kytrinyx Sep 19, 2022
a228bf1
Remove unnecessary 'here' when linking from syllabus docs
kytrinyx Sep 19, 2022
d29d0d7
Add suggestion to syllabus docs
kytrinyx Sep 19, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Tweak syllabus docs
  • Loading branch information
kytrinyx committed Aug 15, 2022
commit 153846fec03b45a3d5ab6afacc68b6837f55167f
19 changes: 10 additions & 9 deletions building/tracks/syllabus.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,16 @@ That said, if you decide to use other exercises as a starting point for your own
Sometimes concepts differ subtly, sometimes radically.
Sometimes concepts don't exist at all.

Define the concepts from the point of view of the language itself rather than in contrast to other languages.
Don't include concepts just because other tracks do.
Not all concepts apply to all tracks.

The syllabus, and therefore the concept tree, should represent the concepts that exist in the language.

In some cases it might be tempting to put a concept in because people often have to work around it by using concepts that do exist.
Rather than doing this, introduce the concept that the language _does_ use, and consider adding an exercise that explains how to use it in that type of situation.

For example, in Go there are no enums.
Instead the Go concept tree introduces constants, and teaches how to use constants in the type of situation where you might use enums in other languages.

## Contributions from the community

Expand Down Expand Up @@ -101,11 +110,3 @@ It's perfectly fine to say that something will be introduced in more depth later

Concepts are understood more deeply in stages and over time.

## Don't include concepts just because other tracks do

Not all concepts apply to all tracks.
The syllabus, and therefore the concept tree, should represent the concepts that exist in the language.

In some cases it might be tempting to put a concept in because people often have to work around it by using concepts that do exist.
For example, in Go there are no enums.
Instead the Go concept tree introduces constants, and teaches how to use constants in the type of situation where you might use enums in other languages.