37

Yesterday I edited 2 of the 3 almost empty Documentation sections of the Introduction to Lucene topic. When I checked the status of my proposed change today I noticed that about an hour after I submitted my proposal, another user submitted a similar edit proposal but with a rather different Hello World example than mine. I guess he wasn't aware of my proposed change.

If I understood this meta question correctly Documentation treats multiple edits as linear, so if one of either edit gets approved, the second edit will propose significant changes to the first one so it's bound to be rejected.

Wouldn't it be better if a Documentation section is locked (or at least the affected section part is) while it awaits approval for a proposed edit? Sure it may slow down writing a bit, but it will prevent people from getting frustrated because their perfectly fine edit got rejected.

Addendum: it looks like a lot of people encountered similar problems:

At the very least I think that it should be made more clear to editors if the section they want to edit already has proposed changes. Right now, the 'all topics view' of a tag does show proposed changes nicely, but I haven't seen any message whatsoever you when you are reading topic contents and decide to edit it.

2
  • 1
    Yes, it would be better. Commented Aug 31, 2016 at 16:07
  • Apparently there is a warning when other people are editing the same topic (see this meta question). So far I haven't seen such a message myself and I was wondering if a similar message is shown when an edit is already proposed (or alone when it is still a draft)
    – THelper
    Commented Sep 3, 2016 at 11:11

2 Answers 2

20

Since SO-Docs are somewhat comparable to Wikipedia articles - many people (partially) edit community content - their solutions to this problem might work for SO, too.

In Wikipedia, if an article has unapproved edits, you only see the latest approved version on the page, but editing shows the unapproved edits as well. This avoids gathering multiple edits to fix the same issues.

The user editing a section with pending changes should get a notification popup when he clicks on edit:

You are about to edit a section that has proposed changes. You will see the latest version of the source code including all proposed edits.

Remember that your changes might be dismissed in case they conflict with the approval or dismissal of former ones. Would you like to review the currently proposed changes first?

[Proceed with editing] [Review changes]

Additionally, put a hint above the editor that the source code contains proposed edits.

1
  • Great suggestion!
    – THelper
    Commented Aug 31, 2016 at 17:47
3

We could use the Git technique: if there are two commits from the same base, they are (usually) merged on a line-by-line basis, or merged manually in the event of a conflict.

For example, if user one submits this edit (edits shown in bold):

Opening Files

To open files, prsse open either double-click on the icon or select the icon and press Enter.

Deleting Files

dleete it with delete

And user two submits this edit (edits shown in italics):

Opening Files

To open files, prsse open

Deleting Files

dleete it with deleteTo delete files, click on them then press the DEL key on your keyboard.

The final diff will look like this:

Opening Files

To open files, prsse open either double-click on the icon or select the icon and press Enter.

Deleting Files

dleete it with deleteTo delete files, click on them then press the DEL key on your keyboard.

(Diff markup for illustrative purposes only and would not be displayed on the documentation page.)

In the event of a conflict, I suggest that the reviewer submit a combined edit that replaces the conflicting edits in the queue, to reviewed by someone else. However, this would have its own issues as pointed out by @THelper in the comments on this answer.

6
  • 1
    I like the idea, but it does feel like a workaround for the actual problem which is multiple edits that are done because people are not aware of earlier edits. Multiple edits will often cause conflicts, so that would result in many manual merges and reviews
    – THelper
    Commented Sep 1, 2016 at 17:29
  • @THelper This is a workaround for the issue where edits to different sections will remove edits to other sections. If there are multiple edits in the same area for the same thing there will be a conflict, but it would be trivial for the reviewer to choose the best one, especially if most are identical.
    – wizzwizz4
    Commented Sep 2, 2016 at 7:44
  • Is that a Git-specific thing? Doesn't e.g. SVN do the same? Commented Sep 2, 2016 at 9:42
  • @PeterMortensen It's not Git-specific, but I don't know what it's actually called and more people here know of Git than SVN.
    – wizzwizz4
    Commented Sep 2, 2016 at 9:45
  • I'm not sure it's trivial to choose the best edit in case of conflicts. Just take the two proposed changes I mentioned in my post. The hello world example written by the 2nd editor is short and relies on multiple libraries. I wrote a longer hello world example which does basically the same, but splits things up in methods to clarify the steps. Also I used only 1 core library. You be the judge which example is better.
    – THelper
    Commented Sep 2, 2016 at 12:15
  • @THelper The one that is... er... well, that's not the point. The point is that, when two edits are proposed, that one does not erase the other, and that edits be considered separately. The conflict suggestion I posted was a suggestion, and I wasn't really sure about it myself.
    – wizzwizz4
    Commented Sep 2, 2016 at 13:38

Not the answer you're looking for? Browse other questions tagged .