Should we display the implementation of the tasks in the documentation?

[PacoVK]

As of now every task has it's own documentation page. This typically consists of the "how-to-use"part and additionally the actual implementation details.
For some tasks these informations cause a lot of text and informations to the user.
There was recently the discussion if we need to have the actual implementation of a task within the docs.
The goal of this discussion is to find out whether we want to provide this implementaiotn details as part of the docs or not.
If we want to keep this information, we should consider how this could be improved, that it's not overwhealming users.

[PacoVK]

From a personal pov, i like the ability to actually see whats inside the task. Especially facing bugs/ errors as a developer (and potential contributor) it makes the barrier to contribute very low.
From a user perspective this information may be too much, and i need to parse which of the informations provided in the docs are really relevant to me.
It may make sense to hide the implementation part in a collapse section. This way the information is still there but a user would have to expand them intentionally.

[rdmueller]

Fully agree. Don't know what will be best. Collapsible will be easy. A link to the sources might even be better.

Another aspect is the config. For some tasks, we just include the part of the config file to explain the config options.

[PacoVK]

For some tasks, we just include the part of the config file to explain the config options.

I assume, you want to point out that the docs should contain at least a written form of instructions on how-to use the task, right?

A link to the sources might even be better.

Agree, maybe both would serve the needs best, having a rough look at the implementation without changing the location might be comfortable, and if i do have an idea what needs to be changed, the link would make it even easier to just find the right spot in the code and file a PR

[mh182]

I think we agree all on the one fact, that the source code should be easily reachable if needed. The main target group is savy enough to probably read Groovy/Gradle code in case the task description is not good enough to explain, what it does.

Fully agree. Don't know what will be best. Collapsible will be easy. A link to the sources might even be better.

I agree with you, links would be better since this would prevent loading information which most of our main target group doesn't need.

Since each of the tasks has its own page and thus the size and load time is reasonable, let's start with the easy picks. Make them collapsible.

Another aspect is the config. For some tasks, we just include the part of the config file to explain the config options.

Configuration is a completely different thing than the source code. The main goal of the documentation is to provide the possible configuration options and what they do.

[johthor]

Is there already an issue for this refactoring? Personally I find the long source code excerpts irritating from a user's POV. I would be willing to work on removing or wrapping the source excerpts if there is consensus on the way to show the source code of the task.

I would prefer a link and a collapsed source block. An Alternative might also be to link to the task's source from the sidebar where currently "Improve this doc" brings me to the source of the task's documentation. "Take me to the implementation" could link to the task's souce code.

[rdmueller]

@johthor I think we have consent that we need to hide the source code somehow but to keep a way to easy navigate to it.
Feel free to come up with a PR which implements the flavour you prefere...