Poll: add completed concept docs to track docs until concept exercises are written

Programming Bash
,
1

While the bash syllabus is in an in-between state, I’d like the concept docs to be published … somewhere. Then mentors can point to them.

For now, how do you feel about putting them in the track docs?

Then, we could have:

1 Like
2

Sounds good to me.

3

I don’t know what happens with a syllabus that is not yet public, but for a track like Python, merged concept docs are already visible (in theory) before there is a matching exercise. See, for example, Complex Numbers.

The problem is that students have to know the URL. Are you suggesting adding links somewhere, to make these docs easier to find? That would be useful.

4

They’d be listed under the What’s going on with section on the track’s home page until they fall off the feed eventually. After that, a student would need to know the URL or check the track repo so yeah adding the concept URLs to the How to learn Bash page would be a good move.

image
image855×868 52.5 KB

5

How would students find those docs if there is no syllabus yet? Or would this require releasing a syllabus first (without having concept exercises ready)?

6

I just did a quick check in incognito. Merged concept docs seem to be visible to anyone with the URL. I think we just need links, even if the syllabus is not yet released. For example: Loops in Julia on Exercism.

7

How would we surface those links?

8

Ideally, we would have a way to configure the track so that the “Learn” link shows up in the track tabs list, even if there isn’t an available exercise. That would require changes to the config.json schema, and changes to the web app that Jeremy doesn’t currently have bandwidth to make.

9

@kotp, do you want to weigh in?

10

A few brainstorms here.

  1. Could you possibly enable learning mode and have just one exercise — basics — then have in the concept/about for basics a linktree for the rest of the concepts, along with a note about concept exercises coming soon? Since all the URLS are https://exercism.org/tracks/<programming language>/concepts, that might an alternate way that is more “discoverable.”

  1. Link off of the About <language> page. (https://exercism.org/tracks/<language>/about) — maybe enclosed in a exercism/note block, to make it more visible? If the list gets too long, it could be enclosed in an HTML

    links go here
    block.

  2. Track Docs, but make it under one link: Syllabus. That way, mentors can remember one link (and students can bookmark it).

  3. Track docs, but also a summary/set of docs in https://github.com/exercism/<language>/tree/main/exercises/shared/.docs – so that students downloading exercises can still get a .txt version. Either with links to the website, or as a set of docs they can refer to. It is duplication, but it might also be nice for students to have local copies of concepts they can refer to.

Edited to add: Having a link in the docs does make it visible as a sidebar in most exercises, on the summary page, and a few other places. One worry is that if that set of links gets too long, then it might get missed or not read through. Here are some screengrabs:

screengrabs showing links

Summary page

image
image2570×2844 941 KB

Exercise [help] tab

image
image3178×1492 428 KB

Exercise start page

image
image1888×2036 462 KB

4 Likes
11

Great ideas! Thanks.

I like #3 particularly.

12

https://exercism.org/docs/tracks/bash

now links to

https://exercism.org/docs/tracks/bash/syllabus

which links to the concept docs.

4 Likes
13

Oh that’s slick. I didn’t know we could do that.

1 Like
14

Nice work! :rocket:

I might do this as a summary/shortcut for Python’s concepts as well. It’s a nice alternative to referring folx back to the concept tree.

2 Likes