Improve code documentation

[TomSteu]

Dear wilson contributor,

I found that the publication arXiv:1804.05033 is insufficient as a documentation of the wilson package. In particular, it provides little information about how the code is organised, what the idea behind the modular structure is and how these parts interact. An automatically generated code overview is no replacement for a proper documentation. Asking the user to read the code itself to gain understanding of the package is arguably a bad approach to software development. The lack of documentation shrouds the entire project in mystery makes it difficult to use the code for anything but the match_run example presented in arXiv:1804.05033. For instance, it is not even clear what the public API consists of. Is Wilson the only class that is supposed to face the user? If so, why does it expose so little functionality? For instance, how does one get direct access to the beta functions? Or is the entire package supposed to be a backend for flavio and smelli? These are very elementary questions which should be addressed in the manual.

[DavidMStraub]

Sorry, clicked the "close" button only accidentally.

First of all, yes, you are right, the documentation is lacking.

Secondly: I don't like your condescending tone. "Bad approach to software development" and all that. This is an open source package. You are very much welcome to contribute to it - including to its documentation!

Yes, the publicly documented API - which is ineed only the Wilson package and its match_run - is very limited. So what? If you want more of its underlying functionality to be exposed with a well-documented API and good documentation, go ahead and do it!

By the way, one thing worth mentioning is that wilson.wcxf is a module that was originally shipped as a separate package wcxf which has a separate paper, see https://wcxf.github.io. You might find some more info about the matching/translation functionality there.

[TomSteu]

Dear David,

Let me start by apologizing for my wording, I might have been pretty frustrated yesterday evening after what I thought would be a quick check using the package turned into an hours-long adventure. Anyways, this was not the kind of message I would have wanted to find in my inbox. It is easy to forget that behind these small projects are only very few people, so criticism is bound to become quite personal!

Thank you for clarifying what is supposed to be the user front end of wilson. I don't think there is a problem with the package having a narrow functionality, I only felt that this should be thoroughly addressed in the documentation, otherwise one (or maybe just me?) may suspect to miss out on certain features.

However, I fully agree with you that one should not feel obliged to implement anything beyond one's own ambition to maintain. Any extension can very well be contributed by someone else. A little caveat here is of course that not every potential user is also a capable developer.

What I disagree with -- and this is possibly a standard that I have set myself and is not shared by everyone -- I would never expect anyone else but myself to contribute a documentation for a public code I wrote. Rather, I would welcome contributors (and users) by having a documentation ready for them to get started.

Anyways, I guess the last bit is only my personal opinion and if you think that there is nothing to be done here, feel free to close the issue.

Sorry for the inconvenience,

Tom

[DavidMStraub]

Yes, fully agree, thanks.

By the way, just to clarify: I am not a maintainer or regular contributer to this package anymore, but I answered because I am certainly among those responsible for the lacking documentation.

[peterstangl]

@TomSteu just a small comment from someone who is neither maintainer nor original author of this package but has contributed some code and is familiar with it: I agree that there might be many things one would want to use this package for that go beyond its public and documented part, which is only the Wilson class and its match_run method. But before getting frustrated by the lack of documentation, there is also another way how to learn about whether something can be done with the package and how to do it, namely describing your use case in an issue on GitHub and asking the people who are familiar with the code about it. And in many cases, this might be actually much more helpful than only a well documented code, especially for a small open source project like this, where all of the original developers will read your question. I'm pretty sure nobody would tell you to just go and read the code yourself. On the contrary, it might lead to interesting discussions about possible use cases and new features that could be added to the public API. In the end, that's also part of what an open source code and development by a community is about.

[jasonaebischerGIT]

Hi Tom,

concerning your comment, I agree that wilson lacks proper documentation. @jackypheno and I are actually planning on writing a thorough documentation, including the full functionality of wilson, its structure, use cases etc, which hopefully might become useful for users like yourself.

In the meantime, if you have any specific questions, feel free to open an issue on a particular problem you have concerning wilson, and we will be happy to help you out with that.

best regards

Jason

[TomSteu]

Dear all,

thank you for your comments and please excuse my initial rant. I am not used to github issues being used for asking questions about how to use a code, but I welcome this approach! I have opened the issue #65 in this regard.

best wishes, Tom

[jasonaebischerGIT]

Dear Tom,

very good, thanks a lot! I will close this issue now.