Suggestions regarding Decidim documentation readability

[sinaeftekhar]

There are some points I would like to draw your attention for future revise:

• [ ] Documentation for the scope, area, and category deserves a better clarification under a parent subject. A more distinct explanation is missing from the documentation.
• [ ] A brief explanation about how decidim connects different components via phases would shed light on these parts, since it is a bit unclear at first, for example, how to relate a particular phase to a component.
• [ ] “Decidim: a brief overview(in https://docs.decidim.org/en/whitepaper/decidim-a-brief-overview/)” is the last section in the documentation, but perhaps it is best to be the first item. Usually users with least prior knowledge would refer to this section first, and then move along the rest of the documentation.
• [ ] Some headings in the main menu are not clear for the user what they represent. For example, the whole section of “Understand” is not clear (for instance, why components are being categorized as a subcategory of feature).

[andreslucena]

Great input @sinaeftekhar!!

A brief explanation about how decidim connects different components via phases would shed light on these parts, since it is a bit unclear at first, for example, how to relate a particular phase to a component.

How about a section in the Phases page?

“Decidim: a brief overview(in https://docs.decidim.org/en/whitepaper/decidim-a-brief-overview/)”%E2%80%9D) is the last section in the documentation, but perhaps it is best to be the first item. Usually users with least prior knowledge would refer to this section first, and then move along the rest of the documentation.

My intuition is that this page is pretty dense and could make newcomers fear that there are lots of things to read before starting to just play with things. I'd prefer to have a smallish Tutorial (like what I mentioned in https://github.com/decidim/documentation/issues/90#issuecomment-1129837323) on how to configure it by example and then link to the (unfinished) Whitepaper if you want to really go through that rabbit hole 😄

Some headings in the main menu are not clear for the user what they represent. For example, the whole section of “Understand” is not clear (for instance, why components are being categorized as a subcategory of feature).

It's clear that this whole "Understand - Features" section needs a big rework. It was written 5 years ago when we still didn't have much of the features described in that section, so there are things that aren't necessarily true there. Did you find it useful @sinaeftekhar?

[ahukkanen]

@andreslucena, regarding your comment at https://github.com/decidim/documentation/issues/90#issuecomment-1129837323

For instance, while writing the docs I differentiate a lot between a Sysadmin/implementer/developer and an Administrator user, and the Documentation System seems to be only applicable to developers.

We discussed about this particular point internally and we agreed very much. There should be a clear distinction in the documentation regarding the different types of stakeholders who are involved with Decidim:

• :computer: Administrators - Learn how to configure Decidim and work with the admin panel.
• :hammer_and_wrench: Instance Developers - Learn how to create your own Decidim platform for your organization.
• :nerd_face: Advanced Developers (core & modules) - Learn how the Decidim core is structured and how to fix bugs and develop new core features.
• :student: Academics - Learn about the background and reasoning for the Decidim platform from the technopolitical perspective.

[sinaeftekhar]

Thanks for thorough response @andreslucena Regarding the first part:

A brief explanation about how ...

What made me confused was that, the necessity of phase section was not clear(and even seemed redundant), because, to me as a person who saw the decidim platform for the first time, budget component was a phase of the process(in which voting was taking place). Also, I was wondering how to connect a phase to its corresponding component. In my instance, there were some phases that had no associated components, so basically they were loosely even connected to the process. It took me a bit to find out that what connects a phase to a component is a link that I should provide when I am creating a phase(worth adding that, up until now, I couln't decode how to provide a correct link, for example, from voting phase to voting component, and I did it only after a bit of experiment(also take a look at the following image):

I was thinking of giving some hints to the readers how these two seemingly separated parts are/can be connected.

The second part of your commen,

My intuition is that this page is pretty

I agree with your point, and won't argue with.

It's clear that this whole "Understa...

Perhaps like categorization of participants, or some spaces that are missing from the list(conferences, elections), etc.