search

scijs / scijs.github.io

Web site for SciJS
http://scijs.net
6 stars 1 forks source link

Overarching documentation/examples #1

Open jakirkham opened 8 years ago

jakirkham commented 8 years ago

Related: https://github.com/scijs/contributing/issues/24

I have been watching the progress on this since about last summer. It seems really interesting and there are constantly lots of packages being accumulated. Though I feel it is getting to a point where it would be good for an outsider like me to get a better appreciation of what is going on. While there are some nice examples in each repo's README, it feels a bit like reading the API documentation for NumPy or SciPy, but it is a bit more spread out. This package listing certainly helps ( http://scijs.net/packages/ ) and has been improving. However, I am not seeing a public link to it on the webpage.

Something that I think would really help is a simple overview. What is the problem that is being solved? NumPy/SciPy clone in JS? How can a developer quickly get started with it given nothing other than say npm? What are a few quick examples that we can start with immediately showing we did something? I think this last point is the most important as it tends to capture developers interest easily. Now that we have done a few examples where do we go from here? This admittedly will take awhile to develop but would be something like here are things to work with views, here are some special classes of tools like differential equation solvers, BLAS/LAPACK operations, etc.

levithomason commented 7 years ago

I found the /packages page via Google. Is there a reason this is not the primary landing page for the docs?

I would expect the GitHub and Freenode links on the current doc home page to be minor links and the /packages page to be the home page.

levithomason commented 7 years ago

I've added the packages link in #2, hope it gets merged!

rreusser commented 7 years ago

Sorry for the lack of response! The short answer is that there are a few scattered contributors, but many of the people who have contributed (myself included) currently have their interests focused elsewhere. If I had the means, I'd drop everything and spend 100% of my time building out scijs, cleaning up what does exist, tracking down and translating robust implementations, building out documentation, marketing, etc. I'm guilty of using ndarray-scratch in some modules in a way that probably just causes people to leak memory if they aren't paying attention. That should go away. I'd like to refactor a couple APIs that were, in hindsight, poorly designed. I did put together scijs-ndarray-for-matlab-users a while ago, but that's a pretty far cry from what needs to happen.

Long story short, I agree! I wonder if maybe the time has come to clean up the big picture so that it's more attractive to contributors who can carry on the effort. I've been able to devote some of my time lately toward learning new things, but the scale of really digging into the big picture of scijs might be a bit beyond what I can afford right now (which is what's preventing me from dusting things off and starting 😞).

</rant>

The interest is genuinely appreciated and I'd love to hear further thoughts! I might be able to budget some time toward working on things again though. Ah, time.