Developer guide

[lilyminium]

Is your feature request related to a problem? Please describe.

We've noted in a few places that a split between the user guide and the developer guide is necessary to

• avoid overwhelming users with pointless detail
• make it easier to find things
• have a central place for developer docs that's not the technical API

Describe the solution you'd like

A focused developer guide.

Questions

• Where should this be? Part of the user guide or in its own repo? I don't immediately know how to store it in this repo but make it available at a different URL / with a different sidebar. Should it be part of the MDAnalysis main repo?

• What should it contain? For example, the user guide currently has a Write your own analysis tutorial. I have targeted it at intermediate users who want to do something easy (e.g. radius of gyration) with existing building blocks. Is this for users or developers? @IAlibay has suggested a split between analysis_from_function and AnalysisBase. The entire contributing section should probably go into dev guide. Can we merge the wiki into it, which has many pages that are not immediately obvious?

ping @MDAnalysis/coredevs

[orbeckst]

New repo + url would be a clean solution and allow the three main strands of documentation to go at their own pace.

[IAlibay]

For example, the user guide currently has a Write your own analysis tutorial. I have targeted it at intermediate users who want to do something easy (e.g. radius of gyration) with existing building blocks. Is this for users or developers?

Personally I feel like as soon as we start talking about MDA private functions you end up in a developer territory. A happy medium here might be to allude to being able to build your own class and point users to the really details "here is everything you can (and should [i.e. how to name your class attributes to be consistent with other classes in MDA]) do with AnalysisBase)"

Can we merge the wiki into it, which has many pages that are not immediately obvious?

I know @lilyminium has already ported a lot of the wiki stuff over. Personally I'd like to see wiki entries like ASV etc.. go into a developer guide. If anything it would make it more accessible for new developers.

Where should this be?

I realise I am contradicting what I said ~ 10 minutes ago off-github, but I am going to change my mind and agree with @orbeckst. Having the dev guide in it's own repo with releases that are immediate & directly reflect the MDA develop branch would be really useful.

[jbarnoud]

While I am not opposed to having the developer guide be completely split in an other repo / separate URL, I do see a drawback that should be considered. By doing this split, we make the transition between being a user and being a developer look harder. Ideally, we want users to seaminglessly become advanced users and dev, with the split in the doc we put up a barrier that, I am afraid, would break this transition for some.This issue can be addressed though. I would keep advanced used in the user guide and make as much bridges to the dev guide as reasonable. This way, a user would land on the dev guide more and more often as they progress and transitionning to dev becomes less scary. This could even bring some satisfaction to some and encourage them to become contributors. On 16 Jul 2020 01:09, Irfan Alibay [email protected] wrote:

For example, the user guide currently has a Write your own analysis tutorial. I have targeted it at intermediate users who want to do something easy (e.g. radius of gyration) with existing building blocks. Is this for users or developers?

Personally I feel like as soon as we start talking about private functions you end up in a developer territory. A happy medium here might be to allude to being able to build your own class and point users to the really details "here is everything you can (and should [i.e. how to name your class attributes to be consistent with other classes in MDA]) do with AnalysisBase)"

Can we merge the wiki into it, which has many pages that are not immediately obvious?

I know @lilyminium has already ported a lot of the wiki stuff over. Personally I'd like to see wiki entries like ASV etc.. go into a developer guide. If anything it would make it more accessible for new developers.

Where should this be?

I realise I am contradicting what I said ~ 10 minutes ago off-github, but I am going to change my mind and agree with @orbeckst. Having the dev guide in it's own repo with releases that are immediate & directly reflect the MDA develop branch would be really useful.

—You are receiving this because you are on a team that was mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.