edu redesign

[daviddao]

BioJS Edu was very useful in the beginning of BioJS 2.0. Right now, it has to be updated and rewritten. Some code examples are already out of date. How about we use docco for documented code and redesign BioJS Edu in that way, that we provide a lot of code snippets for smaller BioJS Components which are well documented. Code explains itself. It also could be used as a library/collection of documentations for all BioJS components.

I would also like to add this point to the monthly BioJS Call as "Documentation of BioJS Components"

[wilzbach]

How about we use docco for documented code and redesign BioJS Edu in that way, that we provide a lot of code snippets for smaller BioJS Components which are well documented

I like the idea - however docco does not provide a hierarchical order of the source files which makes it a bit complicated for larger components to read the doc.

It also could be used as a library/collection of documentations for all BioJS components.

Do you want to provide code snippets about the use of components or the actual component itself?
We could setup a service which runs npm run docon every component and stores/displays the output.

BTW this is related to bionode/bionode#10

[DevasenaInupakutika]

@daviddao @greenify In the process of working on documentation guidelines, Could you please let me know any specific points you want me to address (specific components already created using BioJS2 new framework, edu redesign etc.)?

Also, could you please let me know the reason of shifting to docco as a documentation generator?

[wilzbach]

In the process of working on documentation guidelines, Could you please let me know any specific points you want me to address

• edu redesign: make it easier for people to get started and find the information they need
  • the tutorial series is either too advanced or too simple
  • people only want to access specific parts (e.g. how to upload a package on npm, coding guidelines or how to use slush)
  • convergence with
    • the snippets of components (they are part of the documentation)
    • biojs wiki (there are some FAQs and guides too)
• documentation guidelines: (can we find/agree on) a common way for BioJS packages to document their code

Also, could you please let me know the reason of shifting to docco as a documentation generator?

We never decided to shift to docco. @daviddao just suggested it.

[DevasenaInupakutika]

Thanks @greenify .

I am currently working on DeveloperExperience review which will present a review of BioJS's resources for developers and will be sending that for your inputs, feedback/ comments by the end of this week or at the most on Monday next week. That will also contain the information which developers will seek including source code and documentation management.

documentation guidelines: (can we find/agree on) a common way for BioJS packages to document their code.
Sure, we can then agree on guidelines based on your comments.

[ljgarcia]

On 09/12/2014 10:06, Devasena Inupakutika (di1c13) wrote:

Thanks @greenify https://github.com/greenify .

I am currently working on |DeveloperExperience review| which will
present a review of BioJS's resources for developers and will be
sending that for your inputs, feedback/ comments by the end of this
week or at the most on Monday next week. That will also contain the
information which developers will seek including source code and
documentation management.

|documentation guidelines: (can we find/agree on) a common way for BioJS packages to document their code
|

Sure, we can then agree on guidelines based on your comments.

—
Reply to this email directly or view it on GitHub
#20 (comment).

Hi all,

Not sure if useful but just in case I will share some of my experience
with the tutorials.

I use Windows and some npm modules can be tricky, d3 is one of them. I
already had npm in my machine, but still I needed to install python
3.x.x is the current recommendation, but 2.7.8 was the one that worked
for me. I did not need to use cygwin. The headache started when I tried
to install d3. I guess d3 is pretty common in visualization nowadays so
maybe some tips about it would help, just come links with information
about it. This is the one that I used and worked for me
https://github.com/TooTallNate/node-gyp/wiki/Visual-Studio-2010-Setup.
But some others that I tried and might be useful as well are
http://mlusiak.com/2013/12/22/fixing-failing-npm-packages-on-windows/,
https://github.com/TooTallNate/node-gyp/wiki/Updating-npm%27s-bundled-node-gyp,
http://rainabba.blogspot.co.uk/2014/02/adventures-in-nodejs-using-npm-on.html

http://edu.biojs.net/series/101/22_headstart.html was fine, it is pretty
basic and a good starting for beginners. However, it all changes when
you move to the next step in the tutorial
http://edu.biojs.net/series/101/30_package_basics.html. It recommends
using biojs-slush, which is great by the way. But then, rather than a
couple of files as shown in the initial BioJS component example, you end
up with thousand of files! And you are a beginner, it may be
overwhelming. So, maybe a word on what it is creating (dir structure
perhaps?) and why would be nice.

Then, in the same tutorial you have some available commands, but what is
the recommended flow for them? I end up with multiple terminal windows
open to run the watch, and the sniper, and the build. And maybe improve
the description could help. For instance, "watches all your files and
runs browserify" does not really tells me what is happening there or why
it is useful.

I did not go through the rest of the tutorial, I started playing by own
then. However, I saw that watchify is mentions again later. And then it
is mentioned that it recompiles all changes. It is difficult to get the
right way, because there are different options, different technologies,
but I have the feeling that it could be better organized. Maybe an short
introduction first would help.

Regards,

[DevasenaInupakutika]

@ljgarcia This is really useful in terms of user experience and yes, probably a QuickStart Guide would be good.

[daviddao]

@ljgarcia Thanks a lot for sharing your experiences. D3 has problems with npm (due to its inherently different development style) which makes it not so straight forward to install. I started creating a minimal biojs package, which doesn't require to install biojs-slush as global variable, allowing a free folder structure but comes with the essentials (browserify and biojs-sniper)
@greenify @DevasenaInupakutika our Head Start Tutorial is our very basic QuickStart Guide. However, i think that teaching BioJS is essentially teaching the newest JS technologies and tools - so maybe we can spend more time linking to ressources and just reduce our tutorials to the tools BioJS actually provides (registry, slush and its components)