Initiative Module Review

[arnaumonty]

• [x] 1st Step (choose initiative type)
• [x] Steps bar. Take into account the responsive mobile version. Take into account the creation proposal wizard
• [x] User groups supports in Full Initiative View
• [x] Review initiatives page list. It needs a description at the top of the page about what the initiatives are.
• [x] Review the header of an initiative (initiative example)

[furilo]

Should we start working on this?

cc @decidim/product

(btw, who is in charge of moving issues between states? al least to "Ready", so we know what we should be working on a given moment?)

[xabier]

hi @furilo lets be proactive, feel free to move to ready if you don't need more specs or simply if you want to take a step forward when you feel confident.

[javierarce]

For the 2nd task in this issue (1st Step, choose initiative type) here's our initial idea:

We've worked from the current implementation that can be found in the staging sever and use the same kind of module that can be found in the accountability page

Some key differences:

1. In order to avoid discouraging the users before they have make their mind, we don't show the progress bar at this moment.
2. We've reduced the amount of information the users get when they land on this page, so they can focus on which action they want to take.
3. Related to #2, the options are writing using a straightforward tone "I want to create X", "I want to do Y".

[xabier]

looks great to me! @arnaumonty ?

[xabier]

@jsperezg how do you see this?

[jsperezg]

It looks great.

[arnaumonty]

It looks great to me too. It looks more navigable and intuitive. Nice work @javierarce. We had in mind to display an image in the full description view in order to explain better the types of initiatives.

[javierarce]

Hi!

Here's our proposal for the next steps of the Initiative Module:

https://marvelapp.com/126hf926

You can navigate through each screen on the link above, but I'll explain some our decisions:

1. We've reduced the distance to the top of the form by a) reducing the amount of information in the help boxes and b) placing the progress indicator and the help link in the left column.

2. We've added a reminder of which kind of initiative the user chose and placed consistently in the left side.

3. We've reduced the original 7 steps of the progress bar to just 3 items: create the initiative, validate it, and create the committee.

We hope that, with these changes, the users will have a more clear and straightforward understanding of the whole process, but there's still room for improvement, specially in the last step: we feel that the text at the end could be simplified and be more targeted (for example, we shouldn't need to say "Si has seleccionado la opción de recogida de firmas presencial o mixta, 
deberás subir la información requerida", because at that point we know exactly which option was chosen).

I hope you like it. Let us know what you think :)

[javierarce]

I have a question regarding the last task in this issue "User groups supports in Full Initiative View"… Could you explain me what do you mean by that? I've checked the functional requirements document but I didn't find information about it.

[xabier]

I like it very much @javierarce also downflow of steps is psychologically much easier for participants. Nice one.

One important thing to bear in mind. Iniciatives are proposals within a container. This means that the proposal wizard and the iniciatives wizard should be the same.

Regarding the reduction of steps, some are unavoidable. I wait for feedback from @arnaumonty and @jsperezg

I have a question regarding the last task in this issue "User groups supports in Full Initiative View"… Could you explain me what do you mean by that? I've checked the functional requirements document but I didn't find information about it.

@arnaumonty will explain

[xabier]

I have a question regarding the last task in this issue "User groups supports in Full Initiative View"… Could you explain me what do you mean by that? I've checked the functional requirements document but I didn't find information about it.

This must be adhesions by organizations

[jsperezg]

The problem trying to reduce the number of required steps is basically the atempt of reducing duplicated or quite similar initiatives. We have an step where the user types the title and description. Then if similar initiatives have been found the user can select one and support it instead of start a new one.

This step is invisible when no similiar initiatives have been found.

Of course we could remove this step and force the user fill the entire form prior to look for similar initiatives but IMHO this decission should be taken after some time running the current version. Once we know how efective is this screen we can decide to maintain it or simply remove because it appears few times.

Other solution that we could consider is, depending on the amount of active initiatives, instead of looking for similar initiatives find a way to present currenct active initiatives when the user selects the initiative type.

[arnaumonty]

Hi @javierarce

We've reduced the distance to the top of the form by a) reducing the amount of information in the help boxes and b) placing the progress indicator and the help link in the left column.

Great

We've added a reminder of which kind of initiative the user chose and placed consistently on the left side.

Perfect. It helps to know which kind of initiative you are creating.

We've reduced the original 7 steps of the progress bar to just 3 items: create the initiative, validate it, and create the committee.

Attending the progress bar:

• We can dismiss the first step to "Choose" the initiative type. It works better the new design.
• We can't dismiss the step to compare with similar initiatives, this is an important step.
• The step "initiate" and "create" it seems similar but is not. The first you just write the title and description and the second, after to check if there are similar initiatives, you fill extra information as scope, signature type and author.
• The step "validate" in some cases is not mandatory and probably is not the most important and several times will not appear.
• The "promoter committee" is important and I agree to dismiss the finalization step.

I have a question regarding the last task in this issue "User groups support in Full Initiative View"… Could you explain to me what do you mean by that?

User groups supports are the adhesions and the behaviour should be the same in the whole platform as we are discussing in #156 . This is the list of organizations adhered.

[javierarce]

Thanks for the feedback!

With the reduction of steps, I just wanted to reduce the information that the users see when they use the form, not the steps themselves.

For instance, in the first step ("Crea tu iniciativa") the users would fill the form and, after clicking the "next" button, the page would show them the list of alternative initiatives… but the progress indicator would still show "Crea tu iniciativa", because that's what's the step is about. Internally nothing changes, but we don't show the middle steps.

[javierarce]

In any case, my intention is to push towards simplifying as much as we can, but I understand that is not always possible and there are always downsides :)

[arnaumonty]

I have updated the issue with the defined tasks.

[javierarce]

Hi! Regarding the "steps bar / mobile version" task, here's my proposal:

So basically, in the mobile view we get rid of the bar and replace it with a line indicating the current and number of steps. If you deem them necessary, here's my proposed solution:

Let us know what you think :)

[javierarce]

About the "Review initiatives page list" task. Here's a possible solution using the notification element that we show inside the wizard:

[javierarce]

And here's the adhesion listing ("User groups supports in Full Initiative View").

It's the same idea we have in https://github.com/decidim/design/issues/156 but I've added a link to show the complete list in case there are lots of adhesions:

[javierarce]

For the last item on the list ("Review the header of an initiative") I was wondering what kind of information or actions you'd like to include. What kind of states/phases can initiatives have besides being open/closed?

[arnaumonty]

So basically, in the mobile view we get rid of the bar and replace it with a line indicating the current and number of steps. If you deem them necessary, here's my proposed solution:

We have been discussing with @carolromero and it looks great to us your solution as long as the step bar is displayed when you click in ("ver pasos") and the step bar is hidden by default.

About the "Review initiatives page list" task. Here's a possible solution using the notification element that we show inside the wizard:

Looks nice as an MVP. Maybe in the future, we should review it in order to improve the experience of participants to understand well what the initiatives are. We should apply in the cards the new design defined in #156

And here's the adhesion listing ("User groups supports in Full Initiative View").

Looks great

For the last item on the list ("Review the header of an initiative") I was wondering what kind of information or actions you'd like to include. What kind of states/phases can initiatives have besides being open/closed?

Good question. Our proposal is:

• [ ] Show the period of collecting signatures highlighted, and eliminate the step bar because there is just one step and it doesn't make sense to have it. We have to options:
• Use the text: "The period of collecting signatures is" & (the period dates) "25-12-2017 - 31-12-2017" highlighting the dates.
• The same solution above adding something like "X days left to finish the collection of signatures" highlighted.

[javierarce]

Ok, I think I prefer the first option, since we are currently showing the start and end dates in other headers. I've also added a call to action in the form of a button to be coherent with #161 and a version without the button in case we don't want to implement it just yet.

[xabier]

@javierarce I don't like the sign button on the header, the philosophy here is that iniciatives are a single proposal within a special container (as if they where a participatory process with a single proposal). Adding the action button on the container (so to speak) brakes the experience of suporting/voting/signing proposals/iniciatives, etc. @arnaumonty @carolromero how do you see this?

[arnaumonty]

+1 @xabier @javierarce the third design with no sign button looks great to me but maybe we should try to highlight a bit more the dates because is strongly relevant information for initiatives.

[javierarce]

I'd prefer not to update the format of the date line if is not strictly necessary at this moment, so what about we add a line with the remaining days?

[arnaumonty]

I'd prefer not to update the format of the date line if is not strictly necessary at this moment, so what about we add a line with the remaining days?

+1, great idea. Let's go ahead with this last version.

[furilo]

Hey @decidim/product - @javierarce told me about your conversation re sending the PR about initiatives to its own repo. I guess this maybe it's motivated to the need of each team approving the PRs that affects them but, will we be able to maintain and keep progressing to the component-based decidim_app-design that we have started? Correct me if I'm wrong, but it we have to send different PRs to different repos, we face again the problem of keeping decidim_app-design synced.

Btw, currently we have several PRs opened, and they will start to depend on each other soon as we progress extracting components, and the sooner they are approved, the faster we can progress on extracting components etc.

cc @Crashillo

[xabier]

@decidim/developers @josepjaume how can we put some order on design with modules on separate repositories? this is an integration issues that I don't have the knowledge to solve.

[josepjaume]

@furilo this is really a hard problem to solve. One one hand, we should probably try to reduce any module-specific code to its minimum, as most of the UI components we create can probably be generalized as generic UI elements that the modules can use instead of just creating them.

That said, we're left with the issue of how to deal with CSS specific to each module. Maybe we could treat them the same way we do with the code: Just have a decidim-design_app instance (just a simple rails app) inside these repos. I believe this approach will help decoupling the modules from the core and also encourage thinking in terms of a more generic UI (as we'd have to switch repos in order to create specific code).

If that makes sense, I can create these decidim-design_app (or maybe the should be called "mockups") in each module. Oh, and we should definitely document this and probably even include this on a boilerplate.

What do you think?

[furilo]

@josepjaume if we want to progress to build a library of components, so in the end pages are mainly includes of partials, I don't know how having many design apps will let us achieve that. The only option I can imagine is having -again- a single design app, decoupled from the main repo, which is included in every app-module that is being developed. But this is complex, so for starters I don't like it.

Then again, if I'm not missing anything and my assumptions are correct, I understand that the only drawback of having a design_app inside the main repo is that if a third team is developing a module, someone external to that team has to approve the design PR, right? If this is the problem, I see it as a workflow and rights problem more than a code organization one.

Because if I understand correctly, every module will be include from the main decidim app, so they will have access to the mockup + their corresponding CSS+JS resources.

Another issue would be if we wanted to enable that some team, in a completely independent manner, create a module which requires new and exclusive css+js to this module (if the css+js is non-exclusive, it should go to the common library ie. decidim repo), how they would provide it. But, is this really the case today, or is it going to be in the mid-term?

In the actual context, with some specific teams in charge of producing HTML, I would keep the current setup, have the HTML PRs approved so that the team working on another repo have this available as any other resource of Decidim. When we have an ecosystem of external developers creating modules (we should call them plugins by them ;) we can come back and revisit this problem.

Sadly, this PR approval process would fall under Codegram arms ;), but I think it's a reasonable amount of work. Correct me if my perception is wrong.

[josepjaume]

Hi @furilo - well, it turns out we actually have a team working in independent modules (sortitions & initiatives) in their own repos. We should definitely bundle the CSS & JS in the modules themselves, to encourage modularization of the CSS and separation of responsibilities. It's still unclear if we will eventually move all these repos to the main repo, as most of them are still in the works and need work before we bundle them.

What we can do, maybe, is prototype with decidim-design_app and then copy the styles to the module when finished. If we have a good, consistent set of components in core, the amount of specific code should be very small and won't be a burden. We could still use a PR approach to show the code and discuss it, and copy the styles and move the discussion to the other repo at the end.

So, my take on this: We should focus our efforts on making as less specific code as possible & reusing the same UI components, so most of code can stay in core and you'll be happier developers. On our side, we'll start using cells to componentize view elements so the modules can use them. Eventually, UX, development workflows & code would benefit.

Do I make any sense?

[josepjaume]

So @furilo, if the dream of having a big, consistent, UI toolkit came true, then we could do what you suggested in the beginning: Create a separate repo and develop things there independently. We could even call it decidim-ui and could potentially provide helpers, cells, etc.

That might need a bit more of abstract thinking when it comes to design, but IMHO it's worth the effort.

[arnaumonty]

@josepjaume @furilo The initiative design revision is an exception in the development stage where we are. The initiative module has to be moved to the main repo soon. Let's try to solve the problem attending the needs of this issue and not other needs (like the integration of designs in third-party engines). I'm not pretty sure if the decidim-design_app is a good solution, but following the recent agreements (to include decidim design in the main repo) my proposal here is to wait to PR the designs defined and included in this issue until we have Initiative in the main repo as a new engine (task for @decidim/lot-core ). After that (or during that) the initiative design should be applied in decidim design (@decidim/lot-px ) in the main repo. The initative case was an exeption because the development was made before development lots. During the development of Lots we should be able to coordinate all the developments coming from Lots to the main repo, and this will help to keep all the designs in decidim design app in the main repo.

[furilo]

By independent I meant some team who is not being coordinated by @decidim/product, neither is expecting code from us ;) I would like to go back to the current limitation of having design only on the main repo. Just the PR approval process, or do you see another difficulty?

Also, let me show with an example why I find it difficult to have CSS in different repos: imagine that for initiatives we need to iterate on the design of a card (a common component). If we would have to provide that code in the initiatives repo, would we have to duplicate HTML/CSS with that modification? We would have to face a merge in the future if so, and the rest of the project would not receive this improvement right away... Right now, I would say almost all work we are doing is referred to common components (cards, buttons, steps...), so we would be facing this problem all the time.

[josepjaume]

@arnaumonty yes, we probably will eventually move initiatives to the main repo, but it will probably take long as that needs quite a bit of iteration before, so it isn't probably happening really soon. Also, I'd like to explore workarounds to prevent creating the incentive of moving stuff on the central repository, as this will eventually be a problem for the core maintainers (too much code to test at once).

@furilo if you need to iterate on top of decidim-initiatives, what I'd do is create a new app and reference both decidim-initiatives and decidim by path on the app's Gemfile. Then, when the code is ready, we should issue PR's in the both repos.

If you need to prototype a bit, you can of course do it in the current structure - on a separate branch, and with a separate file - and copy it in the end.

I agree on that this might be a little tedious and probably non-conventional, but splitting the project in this way has yielded quite some good results (the ability for a team to work independently on a feature with nearly 0 friction is not easy to achieve) - let's find a way to be able to keep that collaboration structure working.

[furilo]

@josepjaume I don't understand yet very well the inconvenient of keeping design in decidim (I see no practical inconvenient, more than the theoretical one about code organization)

But, I clearly see many inconvenients of splitting it. And I don't think that being forced to submit the same PR to two repos makes much sense... ;)

Btw, we still have pending merges of several PRs: https://github.com/decidim/decidim/pulls/Crashillo - Who is in charge of this? Let's hope they are approved before new conflicts arise and we have to invest more time fixing them ;)

[xabier]

@arnaumonty yes, we probably will eventually move initiatives to the main repo, but it will probably take long as that needs quite a bit of iteration before, so it isn't probably happening really soon

@josepjaume I was expecting a more fluent procedure. We cannot wait too long before a component to core (despite being developed in a different repo) takes too long to move to core. We have bad experiences with this delays (the accountability component is an example). Should we not integrate it straight-away? PR should have been reviewed already. The initiatives functionality has been deployed in two environments already, tested, aproved by @decidim/product we can't wait too long, otherwise the cost of integration gets increasingly high, including updating design, but not only (translations, backward compatibility, component interoperability, tests, etc.).

Keeping repos separated makes sense when a functionality operates as a real plugin, but sortitions, iniciatives, accountability, etc. are core-functionalities, any democratic organization needs to have those.

Also, another extra reason I see to integrate core-components as fast as possible is that the whole framework is not yet stable (APIs are not working well yet, design is changing, the very features that a component need to have, e.g. polymorphic-follow notification specification, etc.) are changing and being defined. Right now centralization seems developmentally mandatory to me. Once the framework, APIs, design, contracts, etc. are stable it is easier to deploy and maintain separate repos. Right now it seems the cost is too high. I would like to hear what @andreslucena has to say on this.

[andreslucena]

I agree with what @xabier says: we need to move fast for this next months. Once we have a stable release (1.0) then we'll need to have something like @josepjaume said, regarding development_apps by module, but at the moment I think is overkill.

So, I think that the simpler flow would be using decidim/design middleman.

[josepjaume]

Okay, I understand. So what about the following procedure:

• Let's make steps towards moving decidim-accountability into core. This will probably need a bit of refinement - meanwhile, we can keep developing the styles in core and copying them (I hope it doesn't take too long). Once it's in core, we can move them inside decidim-accountability just like the rest of the styles.
• For future modules that can potentially get integrated in core, let's create styles in separate files. When the module is created, we can move the files there and keep working the same way we do with decidim-proposals, etc.

By eagerly promoting repositories into the core, we risk putting incomplete modules in there. My suggestion is doing the same we did with assemblies: Quarantine them by not including them in the meta-gem until we consider them stable.

What do you think about this?

[furilo]

I'd like to focus and remind just one -important- idea: for the foreseeable future, when developing new features (inside or outside the main repo), little specific CSS will be developed for that new feature. Most of the CSS will get into the common Decidim library. That's why I think having styles attached to modules doesn't make sense, because it will only produce extra work and headaches.

I think it makes more sense to invest in an style library that is complete and documented, so third parties can benefit from it, than invest in this more complex workflow (because in the end, it will be time from us that we can't invest elsewhere)

[josepjaume]

Absolutely, 100% in agree with that. It's the most desirable path. That's why I thought maintaining that extra code i each module would be such a burden - but I can see how my proposal is blocking you!

[josepjaume]

The only thing we have to take into qccount is: when developing these improvements in styles, we should always keep them in parity with the markup, so the best way to deliver them would be in PRs with both the styles and the code. What do you think?

[xabier]

How can we (@decidim/product) help on this issues? this is blocking the whole dev community right now. Am I wrong?

[josepjaume]

@xabier thanks for the help, but we've been discussing this for the last weeks and we've found ways to work around the shortcomings. Am I right @furilo ? I think this can be closed.

[xabier]

I leave this for @arnaumonty who has been @decidim/product for this issue.

[furilo]

Sorry for not updating with the conclusion of the meeting we had. The conclusion was that as we are heading to improve the common library, we'll stick to the plan of having all HTML & CSS in decidim-design.

In the future if the project reaches a point where 3rd parties with no central coordination can provide real plugins to the project, we'll revisit the strategy (well we really didn't talk about this, it's just my opinion ;) but in any case let's discuss it in the future).

Please @josepjaume add anything I might be missing!