EPIC: Collaborative Drafts (before collaborative space)

[carolromero]

This is an EPIC

Related issues: #2292

Summary

EPIC description

Decidim permits collaborative and co-creation of proposals. The proposals will be called "collaborative proposals". Each collaborative proposal will be called "draft" until be published (converted to a proposal). The collaborative proposals will have the origin "collaborative proposals". It will incorporate the following functions:

• Creating rough drafts with numerous authors.
• The listing of collaborative drafts
• Comments in drafts
• Asking for help from and accepting the help of other collaborators
• Linking drafts to meetings
• Promoting drafts into an initiative, participatory process or project proposal.

On publish a new entity is created with same title, description, category, scope and authorship, comments and the rest of the meta-information will be kept in the draft which won't disappear. Instead a link to the draft will be added to the new Proposal.

A Collaborative Draft does not have any kind of origin, nor Official, neither Citizen. This attribute will be setted to the Proposal it becomes.

Proposal limit per user: we only check it for the creation of proposal, not co-authoring of drafts.

Main related issues

• MVP: Collaborative Draft MVP #3049
• Implementation details: Collaborative Space implementation details #3079

Specs

Draft navigator and draft-creation button

When accessing the proposal, provided that proposal drafts is activated, the proposal section must:

• Offer a button to view proposal drafts navigator --> @decidim/lot-px design required
• Offer a form to create a draft proposal that allows several authors (Decidim participants or user groups) to be incorporated
• Proposal draft navigator shows:
  • Brief explanation of the page
  • List of proposals with card view
  • Filters by territorial area, categories, tags, open/closed, type of proposal (initiative, process, assembly, etc.)
• A button create draft exist to create a draft
  • The proposal-draft creation wizard operates like the proposal creation wizard

Draft page and actions

• Design required @decidim/lot-px:
  • Access to collaborative proposals from proposals page
  • Collaborative proposals page list
  • List of collaboration requests with accept/refuse actions available for co-authors.
  • Collaborative proposal full page (check this comment)
• Once the draft proposal is created, the user can interact with the draft proposal in the following ways:
  • The user can comment on the draft proposal
  • The user can request to collaborate the proposal as a co-author and this can only be accepted by the author or authors of the draft proposal. CTA: Collaborate
  • Authors of the proposal must be able to accept new collaborators
  • The user can share, follow and embed the draft proposal.
  • The user can flag a proposal to report a content.
• Authors can edit the draft with version control.
• Endorsements apply like in proposals
• Once the authors of a draft decide that the draft is complete they must be able to Publish the draft as a proposal.

Creation work-flow

• Like Proposal's creation Wizard. Only compares between published collaborative proposals.

Request collaboration work-flow

When a non-author-user clicks on the "COLLABORATE" button she requests to become a co-author.
When the button is clicked:

• An email is sent to all co-authors with the request and a link to the draft's detail page.
• A list, under the meta data?, will show pending requests to be accepted/refused (only for co-authors).

From then, they are incorporated into the flow of each of the different types of proposals.

1st Iteration

• The page of the draft will have a summary of activity (metadata box) on the draft that will show the following information:
  • Control Version: When a user or organisation has made a modification to the draft (to the title or description)
  • Number of comments
  • Number of contributors to the draft
  • Number of co-authors
• A proposal that is the result of a collaborative-draft needs to display and identifier and a link to the original draft. --> @decidim/lot-px design-required

Fridge

2nd Iteration

• Geolocation of Collaborative Drafts (setting and map)
• Meetings can be associated to the draft --> this has to be done from the meetings component. When you close a meeting you can associate to a draft in the same way that you associate a proposal.
• Invitations can be sent
• It must be able to link the draft to other proposals on the Decidim platform. This is related to Proposals may be associated via a link in the comments #2288 and it should work in the same way.
• Drafts applicable for projects
• The page of the draft will have a summary of activity (metadata box) on the draft that will show the following information:
  • Number of face-to-face meetings
• Drafts applicable for Initiatives

[mrcasals]

@carolromero can you put the tag of the team assigned to this issue, please? 😄 /cc @decidim/product

[arnaumonty]

I paste some initial (handmade) mockups @javierarce

• Proposal List Page:

• Drafts List Page:
  

• Draft page:
  

[xabier]

@decidim/lot-px please check out, there is some design required here. We are re-using as much as we can and only a couple of new buttons, a card-type, icon and little else is needed unless you come up with extra ideas.

[tramuntanal]

@decidim/product I'm leaving here some questions to be clarified in the next meeting.

1st iteration questions

Listing of drafts

• Design required with M-card

Draft Detail

• Why you mention "Drafts applicable for initiatives"? I'm understanding that a Draft belongs to the Proposals module which corresponds to a Component that can be configured in any space..
• We can see an "estado" label just before the description. What is this?
  • Will a draft have states?
  • un/published? no because on publish the draft will become a Proposal
  • open/closed/withdrawn? how will this states be changed?
• Proposals must have a category. If Drafts will become Proposals doesn't they need one too?

Metadata box

• What's the difference between control version and the number of reviews-contributions to the draft? won't the version increment monotonically at every change?
• Where does the number of reviews-contributions appear in your sketch?
• What are face-to-face meetings?
  • How is this number incremented?
  • Where does the number of face-to-face meeting appear in your sketch?
• What will happen when a non-author-user clicks "COLABORAR"?
  • Will there be a list of pending collaboration requests? where?
  • Will all the authors receive and email with accept/deny buttons?
  • both.., none..?

Authoring

• This feature will imply that Proposals now will have many authors, not only 1 as now.
  • This will require to refactor at least all current notifications to author

Edition

• For edition will we have to reuse the edit proposal form without the author identity select? or new designs will be needed?
  As @arnaumonty noted below, we will reuse the edit proposal form without the author identity select

Design required for

• Listing
  • M-card
• Creation form
• Draft detail
• Edit draff <- Reuse the edit proposal form without the author identity select.

[javierarce]

@xabier @arnaumonty Ok, in terms of elements the drafts seem ok. I'm not sure of the placement of the edit, collaborate, and publish buttons, though.

I'll wait until @tramuntanal questions are answered, I share some of his doubts regarding the metadata box.

[javierarce]

I don't think we need to design a new M-Card for this. All the elements we need are already designed and implemented, we just need to hide elements we don't need:

I'd say to show "Draft" instead of "Accepted", use the color for the "Sin respuesta" state, hide the progress bar, and say "View" instead of "apoyar/support".

[javierarce]

I'll add another questions:

• Can authors publish any version of the draft, not just the last one?
• Is it possible to edit old drafts?
• Is it possible to make an old draft, the current version?
• Are comments associated with each version or do they belong to the proposal itself?
• Do we really need the embed and share buttons?

[arnaumonty]

@tramuntanal

Why you mention "Drafts applicable for initiatives"? I'm understanding that a Draft belongs to the Proposals module which corresponds to a Component that can be configured in any space..

The collaborative space should work on initiatives too. Here's there are two ways to proceed:

1. Drafts as a part of proposals module (and then adapt to initiatives) or
2. Drafts as a new module connected to proposals module
   I'm not sure which is the best option (it's a technical decision), maybe @decidim/lot-core could help advising this. Probably the 1st one is the easiest. If we had that we should think a and decide how to implement this in initiatives in another issue.

Where does the number of reviews-contributions appear in your sketch?

We forget it. We should have it on the draft page, but not in the M card. @javierarce can you add this number in the design?

We can see an "estado" label just before the description. What is this?
Will a draft have states? open/closed/withdrawn?

Yes, open/closed/withdrawn

How will this states be changed?

When a draft is published as a proposal, the state change to "closed". the creator of the draft can "withdrawn" the draft.

Proposals must have a category. If Drafts will become Proposals don't they need one too?

The draft should heritage the category.

What's the difference between control version and the number of reviews-contributions to the draft?

The control version is generated by X changes and can be one or more changes in the same action, the number of review-contributions is the number of contributions done it by different authors. @xabier can you clarify this?

won't the version increment monotonically at every change?

Yes it should

Where does the number of reviews-contributions appear in your sketch?

@javierarce should provide the design.

What are face-to-face meetings?
How is this number incremented?
Where does the number of face-to-face meeting appear in your sketch?

The number of meetings where the draft has been discussed. The relation between meetings and drafts works as the relation between proposals and meetings.

What will happen when a non-author-user clicks "COLABORAR"?

It becames a co-author who can edit the draft.

Will there be a list of pending collaboration requests? where?

Yes, It should be shown in the right bar. @javierarce should include this in the design.

Will all the authors receive and email with accept/deny buttons?
both.., none..?

Just the first author.

For edition will we have to reuse the edit proposal form without the author identity select? or new designs will be needed?

I think we can reuse it.

[arnaumonty]

@javierarce

Can authors publish any version of the draft, not just the last one?

Good point. I would say just the last one.

Is it possible to edit old drafts?

We should always iterate on the last draft. @mrcasals can you confirm this?

Is it possible to make an old draft, the current version?

I would say, attending the control version, no. @xabier what do you think?

Are comments associated with each version or do they belong to the proposal itself?

They belong to the whole draft (proposal)

[arnaumonty]

@tramuntanal I've updated the EPIC with the specs commented this morning

@javierarce we can use the M-Card for proposals attending the following different fields:

• The card type shoud be "Collaborative proposal"
• We will keep all the other fields:
  • Title
  • Authors (will be more than one). Maybe we can show 3 and "...." or "show more" or the number of authors ("and X more")
  • State: Open/Closed
  • Description
  • Category
  • Stats
    • Date: creation draft date
    • Follow
    • Endorsements
    • Comments
• The drafts haven't supports, the main action button is "Collaborate"

[xabier]

Is it possible to make an old draft, the current version?

I would say, attending the control version, no. @xabier what do you think?

We have to start simple and with current features. That means with our control version system, which is simple. I am pretty sure our current control version doesn't allow to re-establish old versions. Only to compare. So MVP: participants can only publish last version. If they want to revert they can always create a new version with old content

[xabier]

@arnaumonty

Will all the authors receive and email with accept/deny buttons? both.., none..?

Just the first author

I think the simpler option is to consider all co-authors equal, it simplifies permissions etc.

[tramuntanal]

@decidim/product I've added a link to the MVP and a "Request collaboration Work-flow" section in the EPIC description in this page.

[agustibr]

About the naming of this this type of collaborative-proposal-drafts,
I think they can be named "Proposal Blueprints" as its a synonym for draft or sketch and means preliminary plan and clearly differentiates them from proposal drafts that are created by individual participants.

Launchpad (software collaboration platform) uses this concept to help track the ideas/features intended to implement over the next releases:

• Launchpad Help: Blueprint
• elementary OS project Blueprints

@decidim/product, @decidim/lot-core, what do you think?

[xabier]

Thanks for your input @agustibr but we really want collaborative to be displayed on the name. Also blueprint has other meanings. How about simply collaborative draft ?

[agustibr]

@xabier, Ok
I thought the name was not decided yet.

[xabier]

@arnaumonty @carolromero are you ok with this?

[carolromero]

+1 to collaborative draft

[javierarce]

Ok, here are some initial screens for the view draft page:

Author view (current draft)

This is the view an author sees when she's looking at the newest/current version of a draft.

Author view (previous draft)

In case the draft is a previous one, we show some indications near the publish button and in the metadata box.

Collaborator view

This is the view for a person that is not an author, but was granted collaboration privileges.

Request access

These are the views for users that 1) want to request access 2) are waiting for a response from an author.

[tramuntanal]

@decidim/lot-px @decidim/product is 1 the current follow button design or 2? I thought it was 2 but now I see 1 in your proposal #2840 (comment)

Follow design 1

Follow design 2

[javierarce]

@tramuntanal It should be the first one. I'll create an issue to update the second one.

[Crashillo]

Design PR #3285

[xabier]

@AlberAG thanks for your input! We are aware of how good collaboration is. But this feature of Decidim is already defined, we can accommodate some input for details, but not macro-features like those present in Gdocs. Synchronous text editing, up to thousands of user is a huge challenge from the programming point of view. And this is not the functionality we are introducing here. We are not introducing anonymous contributions quite yet either. However, surveys and newsletters are already an integral part of Decidim.

cheers!

[arnaumonty]

@agustibr

• When we publish a collaborative draft we should add the following alert message:

"The following action is irreversible. After publishing the draft as a proposal, the draft won't be editable anymore. The proposal won't accept new authors or contributions".

• The action "Close" a draft should be renamed as "Discard".

• When we discard a draft we should confirm with the following alert message:

"The following action is irreversible. After publishing the draft as a proposal, the draft won't be editable anymore. The proposal won't accept new authors or contributions".

[arnaumonty]

@agustibr here the proposal to locate the "discard draft" action.

@furilo please check and confirm that works well this option.

[agustibr]

The action "Close" a draft should be renamed as "Discard".

Hi @arnaumonty, now taking a look at the closing action for drafts, to keep homogeneity in the naming, should it be named "withdraw" as it is in proposals?

cc/ @decidim/product

[arnaumonty]

Maybe yes, at the beggining I thougth that It could generate misunderstunding, the behaviour is not exactly the same, but maybe we should keep the homogenity. @decidim/product thoughts?

[agustibr]

@arnaumonty , before renaming I'll wait for @decidim/product thoughts.

By the way, the closing text for the it's the same as the publish 😅 (it must have been some mistake):

When we discard a draft we should confirm with the following alert message:

"The following action is irreversible. After publishing the draft as a proposal, the draft won't be editable anymore. The proposal won't accept new authors or contributions".

Does this seems right?

After closing the draft, the draft won't be editable anymore. The draft won't accept new authors or contributions.

[agustibr]

@decidim/product , @decidim/lot-px : Do you think it's good, if the alert is shown as the screenshot below?

[arnaumonty]

@agustibr it looks good to me, I'm not sure if the behaviour is the same as other similar alerts. Please, @decidim/lot-px check this in order to unify this kind of designs.

[Crashillo]

To keep consistency, please refer to this designs, for instance:

• https://decidim-design.herokuapp.com/public/consultations-vote
• https://decidim-design.herokuapp.com/public/consultations-vote-confirm

Always there are any modal, let's use reveal foundation classes, copy the general markup, and edit the contents.

PD: Buttons are ok like you've implemented, the links have old designs for that.

[agustibr]

ok, thanks @Crashillo 👍

[arnaumonty]

It looks good to me. If you think that is necessary to keep the consistency, @Crashillo could you provide the design for these alerts?

[agustibr]

@Crashillo I've reviewed the modal styles, I attach a screenshot:

Does it look good?

[Crashillo]

p tag is wrapped by .rowor .column classes, isn't it? Unwrap it. Leave it as a sibling of reveal__header

[agustibr]

Please, @Crashillo can you review the code here https://github.com/decidim/decidim/pull/3109/files#diff-8e1dc6a2bfa4fdf5aca48e1e6501aefc in the PR? it'll be easier

is this file: decidim-proposals/app/cells/decidim/proposals/irreversible_action_modal/show.erb

thanks

[Crashillo]

Review comments in PR