Editing Project:Observatory Users Manual (section)

== Edit Together mode ==
 
=== How to use Edit Together mode ===
 
==== Communicating with the other participant(s) about your Edit Together session before and after ====
1. '''Communicate''' outside of the Observatory for the following—whether by email, phone, or other means.
 
* Notify all people you are aware might be editing the page you wish to Edit Together (including editors, relevant administrators, co-writers, proofreaders, etc.). Specify who is invited to join the session and who should know the session is happening when so they don’t overwrite edits.
 
2. '''Session Initiation:''' Schedule a time when you will engage in an Edit Together session on a page (provide the Editorial site link to the page you want to edit together).
 
* Try to keep sessions short (within a couple of hours) to avoid losing unsaved changes. Agree to Save periodically to avoid losing edits.
 
3. '''Save Responsibility:''' It is recommended to agree beforehand as to one person who has Save and Push responsibility, in case someone is still editing while someone else is Saving. Communicate externally when you’re done and be clear if one party is waiting on another.
 
* '''Default: Save responsibility falls on the administrator or editor''' (if there is only one entering the session), who knows '''not to Leave''' an active Edit Together session if they are last in the session '''without Saving'''.
 
4. After Edits: Communicate externally to '''agree on when you are both/all done''' with your Edit Together session and '''make sure someone has Saved all desired changes''' (or if the changes are meant to be discarded, that you have all opted to Leave the Edit Together session without Saving).
 
* If the page is Published (ignore this if it is still a Draft), make sure the administrator/editor in your session or overseeing your work on this page knows it is ready to be Pushed to the Public site.
 
==== Entering/joining an Edit Together session ====
5. To begin the Edit Together session, one participant clicks Edit Together on the top of the page you wish to edit from the Editorial site:
[[File:Edit Together button.png]]
 
6. You will see a Welcome message. Click “Start” to enter. (You can check the “Don’t show this message again” checkbox if you don’t wish to see it next time.)
[[File:Welcome_to_Edit_Together_Mode.png]]
 
7. Note: Any other User who opens or refreshes the page ''after''** at least one person has joined will see a blinking icon to the right of the Edit Together link telling them there is an Edit Together session in progress (**the blinking icon won’t show up because the page won’t autorefresh if they had the page open ''before'' the Edit Together session started—which is why it’s important to open or refresh a page right before you start any Edits):
 
[[File:Collab Editing Already Exists blinking1.png]]
 
[[File:Collab Editing Already Exists blinking2.png]]
 
8. The second participant (etc.) clicks Edit Together on the same page to join the Edit Together session.
 
* The first/existing participant(s) is/are briefly notified at the top right that someone else has joined. For example:
 
[[File:Edit Together 3 someone else has joined.png]]
 
9. More than two people can join an Edit Together session at a time. (Any Observatory page can only offer one Edit Together session at a time, so any Edit Together session for a page is the only one at that time.)
 
==== Engaging in an Edit Together session ====
10. Click on the person icon to see who else is in your Edit Together session (the number here shows how many participants, including you):[[File:Edit Together participants icon 1.png]]
 
* You will then see who is in the Edit Together session including yourself, for example:
 
[[File:Edit Together participants icon 2 selected New Colors.png]]
 
* You can change the color of a User’s square icon/cursor by clicking on the square in the image above and opening up a color picker. Note that changing any User’s color affects the cursor appearance for all Users in the session, not just you, so we recommend changing your own color before changing others’ (for instance, if there isn’t enough color contrast or if there is a colorblindness accessibility issue):
 
[[File:Cursor Color.png]]
 
 
11. As you edit, you can see other participants’ edits in virtually real time, including their cursor (both if they are selecting text or just have left their cursor anywhere). If you hover over their colored cursor marker, you can see their Username.
 
==== Leaving an Edit Together session ====
12. Make sure you don’t leave an Edit Together session without making sure the designated Save User has Saved your desired changes or is still working in Edit Together mode.
 
* The proper way to leave an Edit Together session is with the “leave” button as shown in Step 13. (Do not refresh or exit the page in your browser during an active Edit Together session without going through Step 13 below.)
* If the person icon indicates only 1 participant and you click the “leave” button without Saving, you might be abandoning unsaved changes without a way to recover them.
** (But don’t count on this if you want to discard changes; make sure to undo undesired changes manually or with the [[Project:Observatory Users Manual#Reset (abandon changes)|Reset feature described below in '''Reset (abandon changes)''']], even if you don’t plan on Saving. Sometimes changes are autosaved and recovered even if you exit without Saving!)
** If you refresh or exit the page in your browser tab/window or leave during an active Edit Together session and you’re the only participant, you risk losing unsaved changes (sometimes they stick, but not always; the best way to leave a session is with the “leave” button). If you refresh the page and someone else is still in the Edit Together session, your unsaved changes may still be in the Edit Together session since they kept it open.
 
13. If one party wishes to leave the session, then that User will see a warning stating that all changes made by the User will remain live as long as the session is active for at least one User.
 
* The “leave” button is to the right of the person icon and to the left of the Save button:
 
[[File:Edit Together Leave button.png]]
 
14. Once a party has left the session, they will not be able to see the Edit Together changes on the page yet because they have not been Saved by the participant(s) of the Edit Together session yet.
 
15. Other participants of the Edit Together will see a brief notification at the top right of their screen when another participant leaves the session:
[[File:Edit Together leave notification.png]]
 
16. Even if one party has left the session, the other party/parties can continue to see the suggested changes and can continue editing.
 
17. A User may '''re-enter''' an active Edit Together session that they have clicked “Leave” on if it is still in progress by clicking “Edit Together” at the top of the page (the same way they did in Step 5).
 
18. Note that '''if the person icon shows the number 1''', that means you are the only participant. The warning will be the standard one whether you’re the only remaining participant in the Edit Together session or not, but '''you have a responsibility to Save if there are desired changes neither you nor other participants have Saved yet'''. There will be no custom warning telling you there are unsaved changes (because if there are changes you have agreed should not be Saved, you can continue with the “leave” button and ignore the standard warning).
 
==== Saving changes during an Edit Together session ====
19. The User who wishes to Save can click the “Save” button at top right the way we would for regular “Edit” (i.e., “Visual edit” or “Edit with form”) modes.
 
* Click the “Save” button a second time in the pop-up (fill in an explanation summarizing what changed, if you wish, in the text box).
* You will briefly see a mint green “Page saved” notification at the top right of your screen once the Save is successful (you will remain in Edit Together mode until you click the “leave” button):
 
[[File:Edit Together Page Saved notification.png]]
 
 

20. The agreed-upon designated User with Save responsibility (usually an administrator) should Save periodically to avoid losing desired changes (every few hours), just as we would with a regular page Edit.
 
21. Note that after Saving:
 
* Users logged into the Editorial site can see the Saved edits.
** However, the public ''cannot'' see the changes until the page is (Published if it has not already been, and) subsequently Pushed by an administrator.
* The page History (accessible by Users logged into the Editorial site) will reflect the changes made in the normal way. The changes are primarily attributed to the User who Saved, with other User(s) who was/were in that Edit Together session appearing after (“Tag: collab-edit”).
 
[[File:Edit Together History.png]]
 
22. Note also that after Saving, the Edit Together session is not closed, and all participants can continue editing.
 
* This means subsequent changes desired to appear on the page need to be Saved again (if you exit the page without Saving, they will not be recovered).
* The page History will reflect each Save for Edit Together mode as it would with normal editing.
 
23. For the changes to appear on a Published page to the Public, the page must be subsequently '''Pushed''' by an administrator (only if the page is set to Published; we don’t Push Drafts)—this is only when all desired edits during the Edit Together session have been Saved by any party and they communicate via email or some other external method that they agree they are done with their Edit Together session.
 
==== Reset (abandon changes) ====
24. If the unsaved changes made during Edit Together are meant to be abandoned, click the three lines (aka “hamburger”) icon to the left of the person icon in Edit Together mode.
 
25. In the dropdown, select “Reset to the last Saved version”:
[[File:Edit Together Reset hamburger.png]]
 
26. A pop-up will appear to confirm that you want to abandon unsaved changes; click the “Reset changes” button if you are sure:
[[File:Edit Together reset confirmation.png]]
 
=== More information about Editing Together ===
 
==== Edit Together sessions ====
 
It’s important to understand that Edit Together mode consists of sessions of editing a particular page between/among parties.
 
==== Only one active session allowed ====
 
* You can only have one active Edit Together session at a time. If you already have a session open in another tab or browser, you’ll receive a warning, and the new login attempt will be denied.
* To join again, please exit the current session properly by clicking the “Leave” button. Once you leave the session, you’ll be able to log in from another device or tab.
* About the availability of Editing a page: Note that if you have a page open and someone else starts an Edit Together session, you won’t know until you refresh the page (or open it ''after'' they’ve begun their Edit Together session). In other words, if you’ve had a page open and are about to Edit it or engage in an Edit Together session on it, '''make sure to refresh the page right before editing''' to make sure you’re the only one editing and there’s no one engaged in an Edit Together session that you’re not aware of. ('''Don’t expect a page to autorefresh and show if someone started an Edit Together session since you opened it!''') On a newly refreshed page you’ll see this red circle icon blinking to the right of the Edit Together link if someone is in Edit Together session (you can enter and see who it is and communicate with them externally if necessary):
 
[[File:Collab Editing Already Exists blinking1.png]]
 
[[File:Collab Editing Already Exists blinking2.png]]
 
 
====Other helpful hints ====
 
* Changes are preserved within the session until they are Saved.
* A session remains active as long as at least one participant is present.
* Users can join and leave the session at will.
* Unsaved changes are visible only to participants within the session.
* Other Users may join the session to any page they have Edit access to.
* Once Saved, changes become visible to authorized readers on the Editorial site.
* In the page’s History, the revision authorship belongs to the User who Saved the changes.
* Other session participants are listed in the revision summary too.
* If the last participant leaves the session without Saving, all unsaved changes will be lost.