![](https://secure.gravatar.com/avatar/31142d3530039f3a83e923abc8f9da50.jpg?s=120&d=mm&r=g)
On the topic of documentation: I'm not really in a position of using Python much these days, but I find that I use the Elegant SciPy book frequently as a reference. In the language of the link, it kind of spans How-To Guide and Explanation (but is still compact), which is a strikingly rare combination in an era where there are seemingly so many resources for any given topic. I wanted to point out some potential use cases for Python libraries, to help build user stories for where effort might go. Python has the advantage of guidance by the scientific community, that other language communities lack. Nevertheless, it might be necessary to work elsewhere, in some environment with no Numpy/Scipy/Scikit stack, to build without much infrastructure, or conversely, to analyze and restate something which "just works" into more traditional scientific language, so that something can be better understood for further analysis, or built on in a more robust manner. Neither of these scenarios can really directly benefit from anything other than conforming functionality against verified implementations. So, for example, speed increases to Python implementations don't really contribute to work of this type, and as well, the obfuscation that comes from optimizations can decrease understanding. So from this perspective, the documentation is the most important part (and plays to Python's original strengths as "executable pseudocode"). The most helpful information tends to be minimal working examples, that have few dependencies, and are annotated so that translation of knowledge to functionality is as straightforward as possible. So a Rosetta Code-style suite of runnable examples is valuable, or other multi-lingual presentations that effectively impart knowledge by abstracting away from language particulars, or expose relationships between seemingly-different structures *across* languages or environments. Working output often does not have the luxury of being contained in a single language, and may very well consist of a bunch of GUI programs with different data formats hooked together, with an algorithm built out of available primitives that happen to be available partly in one, partly in another. So the "understanding" part (which is listed in the diagram of the link as the theoretical knowledge that's most useful when studying) winds up being far more useful in a wide variety of production use cases, where the goal might be closer to embedding scientific understanding into an already running system. On Sat, Mar 16, 2019 at 9:12 AM Stefanie Lück <luecks@gmail.com> wrote:
I am very interested in this question and discussion as well. Maybe we should start a separate thread.
Cheers Stefanie
Am Sa., 16. März 2019, 14:06 hat Yash Sharma <yashrsharma44@gmail.com> geschrieben:
Hey Juan, Thanks for a descriptive reply! I needed to ask you more points regarding the API design that you followed. Can you share some ideas as to how did you go about designing your API? _______________________________________________ scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org
_______________________________________________ scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Phone 917 375 8730 Email david@davidsarma.org Web http://www.davidsarma.org