Closed Bug 839559 Opened 13 years ago Closed 5 years ago

Finish implementing section editing (scroll target header to top, not bottom)

Categories

(developer.mozilla.org Graveyard :: General, defect, P3)

All
Other
defect

Tracking

(Not tracked)

RESOLVED WONTFIX

People

(Reporter: sheppy, Unassigned)

References

Details

(Whiteboard: [specification][type:feature][mentor=groovecoder])

Attachments

(2 files, 1 obsolete file)

What problems would this solve? =============================== There are three issues: First, when we want to make a minor change, we have to see the error or issue, then scroll all the way to the top of the article to click the Edit button, then find the spot where we wanted to make a change. About half the time, we forget what we wanted to do, or aren't able to find the right spot again. Second, if we want to work on an article in sections for convenience and efficiency, we have no way to do that at present. We have to open the entire article. Third, translators currently can't focus on just the areas that have changed. With the large number of minor edits we need to make, or significant changes to small chunks of text, this is a real impediment to efficiency. Who would use this? =================== Most writers would use this. What would users see? ===================== Small edit buttons next to each section heading. What would users do? What would happen as a result? =================================================== Clicking the Edit button for a section would open an edit box for just that section and any of its sub-sections, in-page, so that you can still refer to other parts of the article while you work. Is there anything else we should know? ======================================
Some early work and discussion available in bug 775601.
Summary: Enable section editing → Section editing
Bug 771686 and bug 774186 describe problems related to this. Going to merge them into this bug.
I know there is not much to design here, but there is some. The style of the buttons, the location of the WYSIWYG, what subsections are ignored (see comment 0), etc. David, maybe you could share a screenshot of what you have so far so that we can see what Sheppy thinks?
I must be missing the design update part...
I've been doing heaving logging and debugging of this issue and a quick summary of outcome is found here: https://gist.github.com/darkwing/c085b7353481a46738f2 Somehow once `replace_source` is provided, IDs of sections aren't found; if no replacement source is there, the IDs are found just fine. No idea how this is possible so still looking.
So, adding "tool.injectSectionIDs()" within wiki.content.clean_content()'s replaceSection() call allows the content to be replaced and saved correctly; the downside, however, is that section IDs are saved with content; something I don't believe we want. Am I wrong in thinking they shouldn't be saved? Should be implement a "removeSectionIDs" method? Seems like we're between a rock and a hard place with this, because I'm under the impression we never want to change the "source" HTML from the user. While the content is saved correctly, a 302 is returned from the POST and no content is placed back into the document :(
This is the section edit button: http://screencast.com/t/v65b0x9oh6w
(In reply to David Walsh :davidwalsh from comment #9) > This is the section edit button: http://screencast.com/t/v65b0x9oh6w Thanks for sharing that, David. However, there are many other components of design to take into consideration. Are all of the same editor buttons present? Do the Save and Preview buttons still appear at the top of the page, or do they appear below the inline editor? What about the revision comment? What subsections are ignored? How does the editor reveal itself? Does the whole page reload? Does it fade in with an animation? If so, what kind of animation? This is a very important feature, so I want to be sure our users and (currently rather small) design community have the chance to see the design and comment on it. We don't want to ship the wrong thing.
Flags: needinfo?(dwalsh)
Per your comments: 1. Yes, same buttons there with the exception of Save and Continue Editing; that is not presently available. 2. Buttons appear above 3. No revision comment is presently available for completing, but could be added 4. No subsections are ignored. 5. The editor is not revealed with any effect 6. The page does not reload 7. No fade-in animation. 8. None, though I suppose one could be added if we deemed it necessary Should I be awaiting instruction from others here? What community members are putting together their thoughts? This bug (https://bugzilla.mozilla.org/show_bug.cgi?id=775601) doesn't provide design insight, nor does any comment in the ticket above. This feature does not presently work on the server side which is why its design isn't all together important at the moment; making something that doesn't work look nice is of little value. Here is a more complete screenshot, as this feature has been in place: http://screencast.com/t/ThtTyN169phv I'm unclear on process and will await further instruction before touching again.
Flags: needinfo?(dwalsh)
ubernostrum: The AJAX POST returns a 302 for section edits, which comes from here: https://github.com/mozilla/kuma/blob/master/apps/wiki/views.py#L1133 Instead of this redirect, I believe we want the rendered result returned. I'd appreciate if you'd take a look.
Thank you for sharing all of the detail, David. This change includes both back-end and front-end components. As described in comment 0, it includes everything that writers need to start using section editing. This bug does not provide design insight because it has not yet passed the "Design" phase. You can see this reflected on the Kanban board [1]. The process document explains that a change cannot pass the design phase until a PSD (or detailed mockup) and written description of behavior has been shared [2]. Alternatively, a written justification for skipping the "Design" phase can be provided. We have some community members who have expressed an interest in helping us with design, and we will probably gain more resources over time. At the very least we can collaborate with Sheppy and other writers as we have been over the last couple of months. No problem for not understanding this process completely. There are certainly things I could have communicated better, and it will undoubtedly take us a couple of weeks to get the hang of things. In the meantime, thanks again for sharing your designs. I think they will really help us start a discussion that makes this feature great. [1] https://mdn.kanbanery.com/projects/32137/board/?key=0383ba5f05e165e0eb19d8476654fe9775ce2ca7 [2] https://wiki.mozilla.org/MDN/Development/KanbanProcess#Design
That's all fine. I'll await design specs before moving forward.
One more thing -- you're welcome to contribute to the design discussions too. I just want to be sure we have a decision before we develop and ship.
That design sounds good to me. I do want us to have revision commenting for section edits, but everything else sounds great. Perhaps we can put it next to the save button.
Agree that we have some good stuff here. Especially love that the editor is inline and has save / cancel buttons nearby. Thought I would share a few of my own thoughts: * How do we feel about the Save and Cancel buttons being on the left? I wonder if it would make more sense to put them on the right, since that is what users have probably come to expect. * Some kind of reveal animation might be nice. Maybe even just a simple animation of moving content out of the way to make way for the editor. Not a designer, but wonder if something simple like that would be preferable to the editor just appearing. * Why is there space between the editor toolbar and the editor contents?
Hi! Just contributing with some thoughts over here. This feature is quite well known in other places as MediaWiki. In MW, you can edit all sections (e.g.: H2, H3, H4), the boundary is just the next section with the same level. So if you are editing some content after an H3 tag, it will show everything until the next H3, including any H4s inside. So you can actually edit sections and subsections. In my opinion, the tag itself (H3, H4, the section title), should not be included in the content you are editing. That way you prevent the ID from changing. You should start editing by the immediate next sibling until the next with the same tagName. As for icon placement and art, I guess the edit button should show the pencil (as the main EDIT button) or best: no icon at all, it's pretty self explanatory if it's inlined with the section title, trying to keep all noise to a mininum. The save and cancel icons should be placed where they always are, which I think is top right. I'm not really a fan of doing UX design by committee ("I think this should be better"... "but wait, that icon..."), but this is a pretty easy feature I think. On a sidenote: MediaWiki opens the section (or subsection) in a whole new page (reloading), which gets you pretty out of context, but it's also less noisy/distracting. Off-topic: I would love to see a feature like "Zen Writing Mode" (Github Issues) or "Distraction Free Mode" (Sublime Text 2) for the MDN wiki.
(In reply to John Karahalis [:openjck] from comment #17) > * How do we feel about the Save and Cancel buttons being on the left? I > wonder if it > would make more sense to put them on the right, since that is what users > have probably > come to expect. Yeah, makes sense to put them on the right, since that's where they are in the regular full-page editing UI. > * Some kind of reveal animation might be nice. Maybe even just a simple > animation of > moving content out of the way to make way for the editor. Not a designer, > but > wonder if something simple like that would be preferable to the editor > just appearing. I'd argue that animating the opening would be a separate bug. Let's get it working first, then make it sexy later. > * Why is there space between the editor toolbar and the editor contents? Good question. It does look a little funky. David?
(In reply to Pablo Cuadrado from comment #18) > This feature is quite well known in other places as MediaWiki. In MW, you > can edit all sections (e.g.: H2, H3, H4), the boundary is just the next > section with the same level. So if you are editing some content after an H3 > tag, it will show everything until the next H3, including any H4s inside. So > you can actually edit sections and subsections. I really like that idea. Makes sense, and maintains consistency with the wiki platform most people are familiar with. > In my opinion, the tag itself (H3, H4, the section title), should not be > included in the content you are editing. That way you prevent the ID from > changing. You should start editing by the immediate next sibling until the > next with the same tagName. Not sure how I feel about this. Something about editing the whole page to change a section title seems strange to me, and breaks the convention established by MediaWiki and other platforms. > As for icon placement and art, I guess the edit button should show the > pencil (as the main EDIT button) or best: no icon at all, it's pretty self > explanatory if it's inlined with the section title, trying to keep all noise > to a mininum. Also agree here. > The save and cancel icons should be placed where they always are, which I > think is top right. Sounds like we all agree on this. > Off-topic: I would love to see a feature like "Zen Writing Mode" (Github > Issues) or "Distraction Free Mode" (Sublime Text 2) for the MDN wiki. Good idea. Please use the following form to request this new feature: https://bugzilla.mozilla.org/form.mdn I will work on a Balsamiq mockup in a minute based on all of these discussions. If we have any disagreements on that, we can iterate on it until we reach a consensus.
(In reply to John Karahalis [:openjck] from comment #20) > (In reply to Pablo Cuadrado from comment #18) > Not sure how I feel about this. Something about editing the whole page to > change a section title seems strange to me, and breaks the convention > established by MediaWiki and other platforms. Sorry, I thought MediaWiki worked that way. Wrong! Just checked and it does allow you to edit the section starting with the title. However, being restricted to Wiki formatting, you can't mess around with the source. Agree with the rest of the stuff. I will create the "Zen mode" bug.
Thanks for the insight, Pablo. So at the end of the day, do you think it would be better to include or exclude the section heading itself in the editor?
(In reply to John Karahalis [:openjck] from comment #22) > Thanks for the insight, Pablo. So at the end of the day, do you think it > would be better to include or exclude the section heading itself in the > editor? I guess include will be better, taking into account the possible bugs if you mess up with the section IDs.
(In reply to John Karahalis [:openjck] from comment #20) > Good idea. Please use the following form to request this new feature: > https://bugzilla.mozilla.org/form.mdn Created at: https://bugzilla.mozilla.org/show_bug.cgi?id=841044
Attached image Proposal 1: After (obsolete) —
Design proposal 1: * Before hitting "Edit": See comment 25 * After hitting "Edit": See comment 26 Behaviors: Clicking "Edit" causes the editor to appear (see comment 26) without any animation or page reload. Room for improvement: I didn't know what to do with the TOC, so I just put the Save/Cancel buttons above it. Obviously not the best approach, but not sure what else to do. Next steps: Let me know what you think about this design proposal. Anything at all is up for critique.
(In reply to John Karahalis [:openjck] from comment #27) > Let me know what you think about this design proposal. Anything at all is up > for critique. I think this is fine, especially for starters. Let's keep in mind we have a redesign ahead, and the TOC is going to move out of the document flow into a sidebar at that time, so this little visual quirk won't be an issue for very long. Let's go with it!
Like it! I guess we could use a background for the SAVE & CANCEL buttons, with a little padding (5px?), with the same background color from the toolbar (colorzilla says: #E6E6E6), so it provides more isolation even when over the TOC. OR place it inside the toolbar, 5px from top, 5px from right. I guess the whole block could have some *very subtle* border to provide isolation & context. Maybe a semi-transparent border (that's a bit trickier, but doable). Q: Will the editor stretch to the height of the section?
Awesome feedback, Pablo. Thanks for sharing it. > I guess the whole block could have some *very subtle* border to provide > isolation & context. Maybe a semi-transparent border (that's a bit trickier, > but doable). Not exactly sure what you mean. Do you mean a border around the entire editor or just the Save/Cancel buttons? Also, what do you mean by semi-transparent? > Q: Will the editor stretch to the height of the section? Good question. In the mockup, I assumed that the WYSIWYG would be the same height it is on normal pages. I had to move the section "Ubernostrum" out of the way to make it fit. Not at all committed to this approach, though.
(In reply to John Karahalis [:openjck] from comment #30) > > Not exactly sure what you mean. Do you mean a border around the entire > editor or just the Save/Cancel buttons? Also, what do you mean by > semi-transparent? > I was just thinking of a very light thin line around the whole editor, or a wider border (like 10px) with .75 opacity or so. (Think of a wrapper div with RGBA background). Anyway, it's just a minor idea, I'm not even 100% convinced.
Attachment #713978 - Attachment description: Proposal 2: After → Proposal 1: After
Attached image Proposal 2: After
Attachment #713978 - Attachment is obsolete: true
Design proposal 2: * Before hitting "Edit": See comment 25 * After hitting "Edit": See comment 32 Behaviors: Clicking "Edit" causes the editor to appear (see comment 26) without any animation or page reload. Other notes: * The editor that loads is exactly the size of the section that is being edited. In other words, there should be no scrollbar within the editor itself. * As we all know, I am not a designer. I am trying to make these mockups as complete as possible, but there could be some issues. The color of the border may not the best choice, or maybe the alignment shown is a little off. David should use his skills to fix these problems, rather than treating these mockups as pixel-perfect. Next steps: Again, let me know what you think about this design proposal. Anything at all is up for critique.
I should note, by the way, that to get from "Before" to "After", the user clicks the second edit button from the top. In other words, section editing includes the header of the section that is being edited.
Generally I like it. My only concern with putting the save and cancel buttons inside the toolbar area, is what happens if the user's screen is narrow enough that there isn't room there?
I was wondering about that too. I thought that the main content area of MDN was fixed-width (meaning the WYSIWYG is guaranteed to be a certain width) but this appears not to be the case. Maybe David can say more.
Flags: needinfo?(dwalsh)
I *believe* the WYSIWYG is content area resizes upon window resize
Flags: needinfo?(dwalsh)
The width does resize. Maybe the buttons could go outside, I suggested being a outside with a background also. I don't know how this will be styled, but the buttons container can be positioned absolutely, top: 5px, right: 5px, relative to the toolbars; and on smaller viewports you can position them relatively as a block, above the other tools, through simple media queries, adding a little responsiveness. That's trivial from a CSS point of view.
Some examples: In a narrow viewport with media querying: http://pablocubi.co/mdnux/narrow-viewport.jpg Buttons outside with background: http://pablocubi.co/mdnux/buttons-outside.jpg
I really like Pablo's second mockup, buttons-outside.jpg. David, does this look feasible from a technical point of view? If so, I think we should be all set as far as design is concerned.
Flags: needinfo?(dwalsh)
It's totally doable with a minor hack: having borders on top, left, and right, and positioning the element just a little over the toolbar's top border, so the gray background will overlap the thin line on the toolbar. I think twitter's Bootstrap does this with tabs.
I'm concerned with the bottom placement but I can git it a try. No promise there.
Flags: needinfo?(dwalsh)
That sounds good to me. So for design, let's go with proposal 2 (comment 33) except that the buttons should appear as they do in the second link of comment 39 (buttons-outside.jpg). It sounds like the button placement will take some tinkering, so feel free to tinker. Just please pass the final result by us before we push. David: I am obviously not a designer. While the above design outlines what we decided on, you do not need to treat it as pixel perfect. For example, feel free to change the color of the border or the alignment of the WYSIWYG as long as it keeps with the overall look. Maybe one day we will have pixel-perfect PSDs, but today is not that day.
Yes, exactly. Sorry comment 43 was sort of a run-around. We also decided on the following. I am still iffy on the first bullet point of "Other notes", so if you have any other ideas please let me know. Behaviors: Clicking "Edit" causes the editor to appear without any animation or page reload. Other notes: * The editor that loads is exactly the size of the section that is being edited. In other words, there should be no scrollbar within the editor itself. * As we all know, I am not a designer. I am trying to make these mockups as complete as possible, but there could be some issues. The color of the border may not the best choice, or maybe the alignment shown is a little off. David should use his skills to fix these problems, rather than treating these mockups as pixel-perfect.
Whiteboard: [specification][type:feature] → [specification][type:feature][selected]
Whiteboard: [specification][type:feature][selected] → [specification][type:feature]
Whiteboard: [specification][type:feature] → [specification][type:feature][selected]
Whiteboard: [specification][type:feature][selected] → [specification][type:feature]
Doing some archaeology to catch up on the status of this bug. This commit looks involved: https://github.com/mozilla/kuma/commit/87b20005b31cb5bb34ca9ae4136d8b6a43c8b181
Depends on: 771686, 774186
So I have to be honest. When we first started doing Kanban, I chose to "merge" similar bugs into one. This had the effect of really confusing things here. At the moment, the following defects might still be present. These are the only potential problems I know about. * Section Editing on non-English Docs Fails * Once you've done a section edit on a page, attempting a second one fails Solved a problem I created myself. All in the day of a project manager.
Some more detail & issues found: Conflict resolution failed with permission denied because the conflict resolution form was missing a CSRF token. Adding the CSRF token reveals that section editing was restricted to AJAX-only. That breaks the conflict resolution flow, which jumps out of inline editing and into full-page section editing. Does anyone remember why section editing was restricted to JSON-only?
I don't remember why it was JSON-only ... but if the consequence is only that same-section conflict resolution jumps the user to full-page section editing I think that's fine - it shouldn't happen often. Jean-Yves pointed out some of the bugs we saw last time we enabled this: * Tag data gets lost? * TOC value gets lost?
Was it :uber that changed it to JSON-only?
"and after section editing once you couldn't do it again without reloading the page" -sheppy
Ugh, I think I just uncovered another flaw in section editing that might take a while time to resolve: When the save completes, we want to update the edited section with the changes - that includes the result of KumaScript macros. Meanwhile, we have a deferred rendering system that will serve up the stale version of an edited page until the KumaScript system has a chance to finish rendering the changes. That can take as long as a full minute for some pages. So, section editing has a race condition: Sometimes the immediate feedback to a save will show the previous version instead of the changes we just saved - because KumaScript is still working in the background. One thing I might try is to route a section edit through the "preview" feature, so that just the edited update gets immediately rendered while the rest of the page is handled in the background.
Ooo, yeah, that's gnarly. Were you able to reproduce the issues with tag or toc data loss, or editing multiple sections on the same page view?
(In reply to Luke Crouch [:groovecoder] from comment #53) > Ooo, yeah, that's gnarly. > > Were you able to reproduce the issues with tag or toc data loss, or editing > multiple sections on the same page view? Nope, as far as I can tell, all those things work. Still doesn't quite work for translated docs, though, because it conflicts with the translation interface.
Hmm. This has hurt my brain for awhile, and I'd like to work on something else. Defering this to the backlog for now, and leaving this branch around as where I left off in case someone other than me picks this back up: https://github.com/lmorchard/kuma/tree/839559-section-editing-backend-redux Feel free to vote on this / bump up the priority to get it floated up in the backlog in the meantime.
Priority: -- → P3
Depends on: 774570
Button-to-Somewhere experiment: 1. Add a "section_editing" waffle flag 2. Add Edit buttons at each section header to $edit?scrollIntoView={sectionID} 3. Track clicks to these Edit buttons 4. On the $edit page, use scrollIntoView to scroll the editor window to the section 5. Measure "section_editing" users vs. other users
Whiteboard: [specification][type:feature] → [specification][type:feature][mentor=groovecoder]
Mentor: lcrouch, dwalsh
I'm not sure this would make a good first bug. I remember we had a hard time implementing it ourselves back a couple of years ago. How do we feel about removing the mentors?
I thought https://bugzilla.mozilla.org/show_bug.cgi?id=839559#c56 might be a good first way to try this.
Ah, yeah that looks doable.
Commit pushed to master at https://github.com/mozilla/kuma https://github.com/mozilla/kuma/commit/3d0d0d7550b2747f0170498ed017ed55e97b1830 Bug 839559 - Add basic section editing buttons to MDN Bug 839559 - Add google analytics to section editing
So, I'm playing with this and have some comments: First, this is a great way to start! It does get people to where they want to be without manually scrolling (or should; more on that momentarily). But we do need to capture the fact that the ultimate goal should be true section editing. I know that's complicated and we've had issues attempting it in the past, and I'm not advocating tackling it now. I just hope it doesn't get lost as a long-term goal. Second: On this page -- https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Session_lifetime -- if I click the edit button next to the <h2> "Transmission", I'm getting scrolled to a point somewhat above that -- it looks like I'm winding up at the <h3> "Signaling" but that may be a coincidence. The "Transmission" header is just off the bottom edge of the screen when I do this. The header you click edit for should be at the top of the edit box if possible.
After 3 weeks we've received no other bug reports or blockers. So, I intend to open this feature to ≥ 25% of users so we can analyze user behavior as a split-test.
(In reply to Luke Crouch [:groovecoder] from comment #63) > After 3 weeks we've received no other bug reports or blockers. So, I intend > to open this feature to ≥ 25% of users so we can analyze user behavior as a > split-test. The issue in c#62 still needs to be fixed. The scroll to the section to edit is scrolling so that the title of the section you want to edit is just off the bottom edge of the edit box, instead of being at the top of the box where it ought to be. Can this be fixed?
Mentor: dwalsh, lcrouch
Updated information about the current state of this, as of August 27, 2018. This is what's currently deployed on production: Hovering the mouse over a heading reveals an edit button off to the right. Clicking that opens the editor, places the text cursor on the line including the header, and scrolls the document so that header is at the bottom of the edit box. What still needs to be done: * Fix the scrolling so that the heading is at the top of the editor rather than the bottom. In theory this should be what's happening -- scrollIntoView() defaults to scrolling the element to the top, so I'm not sure why it's winding up at the bottom. * Make the edit button available on at least <h3> headings as well as the <h2> headings it currently works on. I'd actually probably like it to be available on <h4> and maybe even all of them.
Summary: Section editing → Finish implementing section editing (scroll target header to top, not bottom)
MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.
Status: NEW → RESOLVED
Closed: 5 years ago
Resolution: --- → WONTFIX
Product: developer.mozilla.org → developer.mozilla.org Graveyard
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: