add rank documentation

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 40.17%. Comparing base (d73aff3) to head (424c19e). Report is 3329 commits behind head on devel.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## devel #2838 +/- ## ======================================= Coverage 40.17% 40.17% ======================================= Files 94 94 Lines 10262 10262 ======================================= Hits 4123 4123 Misses 6139 6139 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[mturilli]

I think we already discussed about documentation for users vs documentation for developers. This works well for the latter but not for the former. I don't think we can tell to our users to go and read the source code (or the API documentation generated from it) as the sole way to understand the basic concepts of our stack.

[shantenujha]

Strongly echo the importance of this distinction and the necessity to be clear on intended audience.

[andre-merzky]

I think we already discussed about documentation for users vs documentation for developers. This works well for the latter but not for the former. I don't think we can tell to our users to go and read the source code (or the API documentation generated from it) as the sole way to understand the basic concepts of our stack.

Well, it is part of the API documentation and as such I do consider it user facing really. That is not to say that we can include some of the text also elsewhere. Do you have a specific place in mind?

[mturilli]

I understand you consider API documentation user-facing but I am suggesting this is a problem. It is a narrow understanding of users, that assume to reduce users to developers. 10 years ago we were already saying: "I am a developer therefore I look only to API specs". I believe that is still valid today and we need to explicitly agree on that. Once in agreement, the devel team will understand that answering to the question you posed is part of the RCT developers' duties. In this case, you proposed, implemented and release the ranks interface. It is part of that task to understand how to document that interface for all our types of users, not only for other developers. As we have done already multiple times since we started to follow the new devel processes, at today's meeting, we will bring up the current documentation (in its very sorry state) and discuss together what to add to the API documentation.

[andre-merzky]

@mturilli : this should be ready for another review.

[mturilli]

Lift some of the text if useful for a general description and then merge as the documentation specific to the API.

[andre-merzky]

Do you need to lift part of what you wrote here and add it to the user-facing documentation

I am not sure I understand that -- this is the user facing documentation, isn't it? What am I missing?

[mturilli]

I am afraid I am the one to be confused. I see two files: src/radical/pilot/task_description.pyand docs/source/overview.rst Everything that is inside src/radical/... is not user-facing by definition. overview.rst is not currently part of the new documentation tree.

[andre-merzky]

overview.rst is not currently part of the new documentation tree.

Can you recommend a place where the documentation should move to? The task description notebook possibly?

[mturilli]

Yes, task description notebook seems reasonable to me.

[mturilli]

Can we merge?