Editable project instructions

[outoftime]

Make it possible to add/edit project instructions from within Popcode. This would probably be via an option in the hamburger menu (maybe in an “Instructor” submenu?)

https://github.com/andrerpena/react-mde might be useful.

[jwang1919]

@ajgreenb and I are looking into this!

In a recent Popcode meeting, we discussed that the first revision of the editable instructions will be open to any user. There is a potential case where a student can intentionally edit and tamper with the instructions to render them useless, but we considered this scenario very unlikely.

As for the workflow on what happens when the "Edit Instructions" link is clicked, we are still brainstorming possibilities... 1, Render the instructions panel to be editable and add a WYSWIG editor tool on top.

2. Open a popout that contains the a WYSWIG editor
3. Possibility 1, plus all other panels are minimized.

[outoftime]

@jwang1919 @ajgreenb looking forward to seeing what you guys come up with! FWIW I would be inclined to do the simplest thing first which would probably be option 1 with no editor tool (either a plain-text Markdown editor or something like react-mde). You can always follow up with more bells and whistles!

[ajgreenb]

I say we start with a plain-text Markdown editor and see how far that gets us before adding a dependency on react-mde. How does this sound, UX-wise?

All projects start with a basic instructions boilerplate (stored in project state.) Maybe something like

# Project Title

You can add **bold text**, _italic text_, or `code`.

1. Ordered lists
2. are also
3. available.

## Sub-heading

* Same
* with
* unordered lists!

If you load Popcode normally and instructions is unmodified, the panel will be hidden from the UI. If it's been changed from the default, it will be visible and expanded (similar to current behavior for instructions from Gists.)

If you load Popcode with the ?admin query parameter, the instructions panel will be visible, expanded, and in editing mode. The top toolbar will have an icon button that toggles between

📝 Edit

and

💾 Save

"Save" saves the instructions to state and renders the Markdown. "Edit" switches back to editing mode.

Thoughts? Does that cover all the possible states?

[jwang1919]

I say we start with a plain-text Markdown editor and see how far that gets us before adding a dependency on react-mde. How does this sound, UX-wise?

I agree, I would like to first start with a basic editor then go for the nice looking UX.

All projects start with a basic instructions boilerplate (stored in project state.) Maybe something like

Haven't thought of this before but makes sense!

If you load Popcode normally and instructions is unmodified, the panel will be hidden from the UI. If it's been changed from the default, it will be visible and expanded (similar to current behavior for instructions from Gists.)

I was looking into this yesterday (and relearning React 😢).

If you load Popcode with the ?admin query parameter, the instructions panel will be visible, expanded, and in editing mode.

I thought we decided against this approach and opted for adding an extra link in the Hamburger Menu. This way is more intuitive for non-coders and works better when instructors need to edit Popcode projects that don't have existing instructions. The obvious downside is that a student can edit the instructions, but I don't think we really need to worry about that.

The top toolbar will have an icon button that toggles between

📝 Edit

and

💾 Save

"Save" saves the instructions to state and renders the Markdown. "Edit" switches back to editing mode.

If we add the "Edit Instructions/Add Instructions" link on the Hamburger menu we can avoid adding an Edit button. There does need to be a Cancel button ❌, where clicking on it reverts the instructions to the previous instructions or no instructions they were not present before.

[outoftime]

Loving this thoughtful discussion! A couple of thoughts:

• Definitely down to start with a plain text editor
• While Popcode’s usage is overwhelmingly within the ScriptEd community, we do want to make sure it’s usable for educators outside of the ScriptEd ecosystem as well. For that reason, I’d prefer not to hide first-class features of the tool behind a query parameter. Definitely open to having an “instructor mode” which can be switched on and off (probably via the good old 🍔menu) but I think for now the simple approach of just putting the Add/Edit button right in the hamburger menu is a sound one.
• I’m generally not in love with the idea of having the actual default value of the instructions field be a big formatting guide—in most cases that would just create an extra step of deleting the boilerplate before starting on writing instructions. One thing that might be nice is to use a placeholder property, although I’d also be fine with borrowing GitHub’s approach of just putting a Styling with Markdown is supported message below the editor that links to a good Markdown guide.

[ajgreenb]

That all sounds 💯 to me! Glad I dropped a comment on the issue before writing a bunch of code 😄

[ajgreenb]

If there's only a Add/Edit Instructions button in the hamburger menu and a Cancel button in the Instructions panel (that just reverts the instructions to the previous instructions or no instructions if they were not present before), at what point do we get the rendered Markdown view vs the plain text "editing" view?

As an example, say I open a fresh project and click Add/Edit Instructions. The Instructions panel appears, expanded, in editing mode. I type some text. Now I want to stop editing, but I want to keep the instructions I've added (i.e., I don't want to Cancel.) With just those two buttons, there's no way to switch to the rendered Markdown view without refreshing the page (or, like, clicking outside the editor?)

I can think of two alternatives:

1. In addition to Cancel, you also have Save. When you click Save, the instructions switch to a rendered view and the Save button disappears (or is disabled). To switch back to editing mode, you'd have to click the button in the hamburger menu again. This is similar to my initial idea.
2. When you're in editing mode, the button in the hamburger menu switches from Add/Edit Instructions to Save Instructions. Clicking Save Instructions switches the panel to rendered mode and toggles the menu button back to Add/Edit Instructions.

Of those two, I think I prefer (1), since it's more discoverable. Either of you have any other solutions that I'm missing? I might be tunnel-visioning.

[outoftime]

@ajgreenb definitely agree that (1) is the better UI!

[ajgreenb]

All right, gotta WIP PR up. The functionality isn't all there yet, but I wanted to get feedback/work in the open as much as possible. Please take a look at your convenience!

@jwang1919 Let me know if you'd like me to save any of those specific tasks for you.