Problem codenames don't match

[sahi1l]

Describe the bug It is hard enough to deal with problems with names like pp_3_9, even harder when they have multiple names, like iter-11-16. An effort should be made that the official code for any problem is actually displayed in the text as such.

To Reproduce This is an example:

1. Go to the Assignments tab, open Problems, and open the Iteration folder.
2. In the Exercises subfolder, click on "pp_3_9"
3. See that the text of the problem calls it "iter-11-16" instead.
4. Visit the Exercises page in Chapter 7, and see that "pp_3_9" appears nowhere on that page.

Expected behavior If we're using codes, they should be the same codes everywhere. I should be able to look through the exercises page, make a list of the problems I want to assign, and then find them easily in the Assignments tab.

[bnmnetp]

So let me give a little history on this and then I would love it if we could all come up with a solution for how to deal with this across the books and Runestone.

1. The names like pp_3_9 are the official identifiers for each problem. These names MUST be unique across the entire book. These are the names that we use when we write a questions using .. blahcomponent:: uniqueid

2. These names should NEVER BE CHANGED once a question is in the system. Assignments use them, the logs use them, the grader uses them, everything uses these names to refer to a question.

3. We used to display the unique ids in the textbook for everything. However, some people didn't like that and wanted a more user friendly name. Fair enough. So we decided to hide the unique identifiers and generate "display names" when the book was built, this way everything could be numbered somewhat sensibly on each page of the book, and allowed an instructor to verbally assign iter-11-1 through iter-11-5 as homework.

THEN CAME THE ASSIGNMENT BUILDER

When we added the assignment builder to Runestone many instructors stopped verbally assigning things and started creating assignments. But the database didn't know what the "display name" for corresponding to each unique id even was. Even worse, before this fall one teacher might build their book in June and another might build their book in September but in the meantime we had added some exercises to the textbook, so for one instructor item-11-1 through iter-11-5 might not even be the same problems! Thats not really a problem any more as everyone sees the same book.

Also, early on, yours truly didn't really think that anyone would assign any problems except for activecodes. So not true! I also was totally random in the way I named questions.

What to do now?

1. The easiest solution would be to add back the caption to everything that shows its unique identifier.

2. We could add a "display name" to the questions table in the database and a parameter to every component that would allow us to define a more user friendly name. These names should also be unique to a book so there is no confusion. They could be used in the assignment builder and displayed by the questions in the text. These names could be updated if need be because we would continue to use the current ids as they are currently used. The "friendly name" could default back to the "unfriendly name" if a friendly name isn't yet supplied.

I'm not sure how easy / difficult this will be in the question builder as I think we rely on the node name being the unique identifier -- hopefully @bjones1 will know.

This would be a LOT of work to update every question so it can't happen over night, and to do it right would require some real thought on the part of authors to come up with a sensible naming convention.

Is there another way? A better way? help!

Adding @RunestoneInteractive/authors to the discussion

[sahi1l]

Number 1 would suit me just fine. You could tuck it away in the upper-right corner with a lighter font if its appearance bothers people. I wouldn't use iter-11-1 as a way of communicating from teacher to student; instead I would just number the problems on each page, and tell students to do "Problems 1-3 on the exercises page of Chapter 7". A potential compromise for #2: give each problem an optional "description" entry, and display that description in a smaller grey font on the Assignment Selector page right underneath the code, or maybe as a tooltip when you hover over the codename. They wouldn't have to be unique that way, and we could slowly build up our supply of descriptions instead of having to do it all at once. (I'm not sure what the Tags field is for, but that could be an alternative.)

[bhoffman0]

I think the easy option #1 is good for now. I realize now that I should have renamed all the exercises that I forked from the old book before making the new book public, but oh well. #2 just sounds too difficult at this point. Could whatever code generates the current display names chapter-lesson-number write that association with the unique name in the database for us and then be used in the assignment builder? -Beryl

On Thu, Sep 19, 2019 at 11:58 AM sahi1l notifications@github.com wrote:

Number 1 would suit me just fine. You could tuck it away in the upper-right corner with a lighter font if its appearance bothers people. I wouldn't use iter-11-1 as a way of communicating from teacher to student; instead I would just number the problems on each page, and tell students to do "Problems 1-3 on the exercises page of Chapter 7". A potential compromise for #2 https://github.com/RunestoneInteractive/fopp/pull/2: give each problem an optional "description" entry, and display that description in a smaller grey font on the Assignment Selector page right underneath the code, or maybe as a tooltip when you hover over the codename. They wouldn't have to be unique that way, and we could slowly build up our supply of descriptions instead of having to do it all at once. (I'm not sure what the Tags field is for, but that could be an alternative.)

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/RunestoneInteractive/fopp/issues/259?email_source=notifications&email_token=ABC4GOTBDTY33LOHS7IHEA3QKOOSNA5CNFSM4IYLPIV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7D7EYI#issuecomment-533197409, or mute the thread https://github.com/notifications/unsubscribe-auth/ABC4GOTRPEVXALQA62S5GZDQKOOSNANCNFSM4IYLPIVQ .

[bnmnetp]

Option #1 was particularly easy thanks to inheritance!

So, here is what I have at the moment. I think it works well with our activity counts... For example:

Continuing to the bottom of the page:

The counter is generated by the CSS! I struggled with whether to do a counter at all and what to put in front of the number if anything, then I thought activity is kind of nice because it mostly matches.... There is just a tiny bit of dissonance due to counting the loading of the page as an activity.

I think we can now remove the other labels like data-13-1 and just go with the captions underneath??

What do you all think?

[presnick]

Activity 0 is loading the page! You're teaching them that indexing starts at 0.

On Thu, Sep 19, 2019 at 2:30 PM Bradley Miller notifications@github.com wrote:

Option #1 https://github.com/RunestoneInteractive/fopp/pull/1 was particularly easy thanks to inheritance!

So, here is what I have at the moment. I think it works well with our activity counts... For example:

[image: Screen Shot 2019-09-19 at 1 24 36 PM] https://user-images.githubusercontent.com/51115/65270587-1701c700-dae1-11e9-8fba-7879f7d2ddef.png

Continuing to the bottom of the page:

[image: Screen Shot 2019-09-19 at 1 24 36 PM] https://user-images.githubusercontent.com/51115/65270593-1f5a0200-dae1-11e9-9305-db79c82b267b.png

The counter is generated by the CSS! I struggled with whether to do a counter at all and what to put in front of the number if anything, then I thought activity is kind of nice because it mostly matches.... There is just a tiny bit of dissonance due to counting the loading of the page as an activity.

I think we can now remove the other labels like data-13-1 and just go with the captions underneath??

What do you all think?

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/RunestoneInteractive/fopp/issues/259?email_source=notifications&email_token=AAIG7TU6NYNEDGMFBBOONXLQKPALJA5CNFSM4IYLPIV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7EM7LQ#issuecomment-533254062, or mute the thread https://github.com/notifications/unsubscribe-auth/AAIG7TSMPXU6RFEPXXHLEWLQKPALJANCNFSM4IYLPIVQ .

[bnmnetp]

True, I think that is a better lesson than having the first activity on the page numbered as Activity 2.

[bhoffman0]

I like what you've done! However, please don't delete the label at the top because we use those in our lesson plans for each lesson and it will be a pain to go back and edit them all. -Beryl

On Thu, Sep 19, 2019 at 2:44 PM Bradley Miller notifications@github.com wrote:

True, I think that is a better lesson than having the first activity on the page numbered as Activity 2.

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/RunestoneInteractive/fopp/issues/259?email_source=notifications&email_token=ABC4GORXAHLFSYA3I46WJ23QKPCAHA5CNFSM4IYLPIV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7EOILY#issuecomment-533259311, or mute the thread https://github.com/notifications/unsubscribe-auth/ABC4GOVUVMVZRGKQX3RJEFLQKPCAHANCNFSM4IYLPIVQ .

[bnmnetp]

Good point Beryl, we can maybe do that at a later time, or make it configurable per book (sorry @bjones1) 😄 It may be better for you in your book as you have probably done a more consistent job of using those numberings than we have in FOPP.

I agree, it would be bad to remove them without any warning as there may be teachers referring to them in any Runestone book.

[bnmnetp]

On the assignment page they look like this:

No Activity # included.

[bjones1]

I'm confused -- is the proposal to use the div_id as the identifier for the question? If so, I am strongly opposed. IMHO, this is an internal name, used only as a unique identifier. In my books, I simply generate random strings for these, so that have no meaning for users or instructors.

Instead, I think the assignments interface should be updated to:

1. Display the problem type, as is show in the tree picker.
2. Display the first few words of the HTML for the problem, which will often include the problem number.

[sahi1l]

All I want is to be able to look at the Exercises or Assessment page, jot down some problems that I want to assign for homework, and then find them in the assignments tab. Using the first few words of the HTML might suit that purpose, unless we end up with a whole page of problems that say "Write a program that…". Much better if each problem had a one-sentence description (or maybe a set of tags) that was specifically written for the assignments tab. Perhaps the description page could be auto-filled with the first few words (minus stopwords perhaps?) as a starting point. But I like having the div_id displayed on the assignments tab simply as a backup.

Also, problem numbers should not look like div_ids. e.g. "iter-11-1". That's just confusing.

If you REALLY wanted to be ambitious, give instructors the ability to "star" questions that appear in the book, and highlight those problems in the assignments tab.

[bnmnetp]

@bjones --- the div_id has always been used as the identifier for the question.

What this is doing is restoring old functionality (displaying the div_id) on the page of the book. We have used the div_ids in the question picker since day 1. This is not a change to that at all, it is simply trying to make it easier for instructors to match up what they see in the textbook and what is in the assignment builder.

[bjones1]

Good point. I think, long term, we need something other than the div_id, since it's not descriptive enough. If I'm correct, anything that can be graded has a problem number autoassigned to it (that is, anything that inherits from runestone.common.runestonedirective.RunestoneIdDirective). This number seems to me to be the easiest and clearest way to identify a problem, without showing the div_id. But doing so will require a change to the assignment interface to show that value.

[bnmnetp]

@bjones1 -- I think you are asking for something like option #2

Some books are better than others at specifying the qnum information necessary to create the descriptive numbering that Scott does not like. Although I think he would be fine with it if we used those names in both the book and the assignment builder.

If you don't want to display the captions as I have currently implemented them (option #1) you can simply change the css. This is a good short term solution gut the long term solution of having a more descriptive number is better.

[bjones1]

Sounds good.

[sahi1l]

I don't like it because it looks like the div_id but isn't, so it has thrown me off several times. It's intended for human consumption but looks like something intended for machine consumption.

[bnmnetp]

OK, maybe I just suck at naming things. But what sort of convention would work? I think they need to be reasonably short and yet still descriptive? Take this page as an example: https://runestone.academy/runestone/books/published/fopp/SimplePythonData/StatementsandExpressions.html

Personally, I think that the captions I am showing in the screen shots from yesterday are FAR better than what we have in place. I like that Activity x has a meaning that makes sense to the student, and they can ignore the identifier.

The descriptions that we generate like iter-11-1 are supposed to remind that these are part of the iteration chapter. I don' think that question-12-25 (the 25th question of chapter 12) or question-12-1-5 (the 5th question of chapter 12.1) is really that helpful.

The approach of adding a star or favoriting a question seems nice to me, and maybe that is a great way to go for the long term.

I don't like using the first few words of the question as I think it would be unhelpful and overly long. everything in designing the interface is a tradeoff between how much space you can use and how much information you can present.

[bnmnetp]

Personally, I would turn off the labels at the top in the FOPP book as they are used very inconsistently.

[bjones1]

I agree on strange labels. I also find them confusing. When they're not set, the numbering makes a lot of sense to me. Here's a screenshot of my book:

I'd like to remove the captions as soon as we can get at least the problem number in the assignment interface, since I think they distract, but are also the best way for now to determine what problems to assign.

[bjones1]

What assignable things don't have problem numbers?

[bnmnetp]

activecodes are on the excluded list for some reason.

[bnmnetp]

There were a lot of objections to numbering like Q-1, Q-2 as they were not descriptive and highly repetitive.

[bjones1]

Hmmm, I'm surprised. To me, a problem is uniquely identified by its page and number on that page, much like a traditional textbook typically presents problems identified by chapter and problem number. So, if I tell students to work on Q-1 on page blah, they know where to go. Likewise, if I want to assign Q-1 on page blah, I know exactly what I've assigned. This, as I see it, is the purpose of numbering problems.

Do other instructors intend the numbers to also describe the type of problem? As in "this is the second instance of an activecode question about lists" or something like that?

[bnmnetp]

perhaps this is all from an earlier time -- before we were numbering chapters and sections, maybe before we were having subchapters.

[bjones1]

That's my guess -- at one point, the numbering was broken/inconsistent, so the books had to use something else. Now, with working numbering, we should use that.

[bnmnetp]

So, maybe some things to clean up and or work on but we seem to be converging toward something that can work...

1. I just added a database field to the questions table called qnumber - this stores the string generated by RunestoneIdDirective.getNumber()
2. The value for qnumber for questions not in the UNNUMBERED_DIRECTIVES list is now stored in the database when the book is built.

TODO

• [ ] Update UNNUMBERED_DIRECTIVES to remove activecode, video, YouTube, codlins, showeval, and poll -- these all should be numbered as they are all assignable
• [ ] Update _add_toc_and_questions to include the qnumber information
• [ ] Update admin.js to use qnumber instead of div_id when it displays the picker
• [ ] Update all directives so that qnumber is added as a data- attribute
• [ ] Update the caption code that now displays the div_id to display the qnumber information so that question numbers are displayed in a consistent way for all assignable questions.

[bnmnetp]

@sahi1l if the caption for the question is iter-11-1 AND the assignment builder displays iter-11-1 then I think you are just as happy as if the the caption showed ac2_1_13 in both places yeah?

And maybe even better because things on each page will be numbered sequentially...

[presnick]

I find the iter-11-1 style captions to be very problematic. In fopp, we aren't good at about restarting the numbering in each chapter or subchapter.

Moreover, when a student post a screenshot or descriptin showing a problem with one of the questions, it doesn't have an identifier that I can use to search for the question in the database or in the book.

I like the idea of a display tag as a new field, with fallback to showing the div_id if there's no display tag for that question. Brad's #2. I think it solves immediate problems and gives a path forward for slowly adding the display tags.

On Fri, Sep 20, 2019 at 2:28 PM Bradley Miller notifications@github.com wrote:

@sahi1l https://github.com/sahi1l if the caption for the question is iter-11-1 AND the assignment builder displays iter-11-1 then I think you are just as happy as if the the caption showed ac2_1_13 in both places yeah?

And maybe even better because things on each page will be numbered sequentially...

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/RunestoneInteractive/fopp/issues/259?email_source=notifications&email_token=AAIG7TQIIBTJ5XUEU4HPAADQKUI33A5CNFSM4IYLPIV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7HQYNA#issuecomment-533662772, or mute the thread https://github.com/notifications/unsubscribe-auth/AAIG7TS5ONLU76M4FLS3XQTQKUI33ANCNFSM4IYLPIVQ .

[bnmnetp]

@presnick - I agree that we are not good about that. But, others have been, and its actually pretty easy for us to fix.

I guess the question I have is whether or not the generated labels such as iter-11-1 are better fallbacks than the div_id.

By fallback I mean what we use when there is not an explicit display name given as part of the directive. I think this actually would make both sides of this debate happy. Those that want auto numbering with a consistent display will get that. Those that want to provide names will get that.

[bjones1]

How do authors provide an explicit display name for a problem? Is this only for certain question types, or does it apply to everything?

I agree with Brad that identifying problems by number and page is the way to go.

[bnmnetp]

@bjones1 the idea is that we would add a new global option for numbered components that would allow the author to add a description.

[bnmnetp]

I think this is one of those places where we have to acknowledge that not everyone is going to agree on the right/best way of doing something, and if there is a reasonable way of providing flexibility to make everyone happy then we ought to do so.

[sahi1l]

The generated problem numbers make more sense to me now that I understand that they are independent of the div_ids; I had mostly ignored them until today, not noticing any particular pattern to them. I now think switching to using the problem numbers on the Assignments tab instead of the div_ids would help a lot. It will also make it easier to distinguish between the "built-in" exercises from the textbook and the contributed ones from other sources, which I think is a bonus.

[bnmnetp]

Thanks @sahi1l -- That is the direction that we will move toward. For the moment we are at least consistently displaying the div_id for all assignable components, which I think is a nice step forward. In another week I think we can be at the point where we show the generated problem numbers in both places.

But this does raise an important point about how we determine what will show up in the assignment builder:

1. If the instructor explicitly adds a :label: we will use that in all places.
2. If there is no explicit label, but there is a generated label (.. qnum::) then we will use that in all places.
3. If there is no explicit or generated label then we will have to use the div_id as the final backup.