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)

[DevasenaInupakutika]

@greenify @daviddao In the process of working on notes for documentation guidelines, I would need clarification on certain terms to be used. One or two examples for these would help in this case.

1. BioJS components
2. Packages (Packages are same as components?)
3. APIs available in BioJS (from the discussion in the last call)

[wilzbach]

Sorry for the late response.

1. BioJS components

Biojs-vis-msa, biojs-io-fasta

1. Packages (Packages are same as components?)

Yes. Basically a npm package is a biojs package. However at least I differentiate between visualization components and non visualization - maybe we could define a component as a package with visualization?

1. APIs available in BioJS (from the discussion in the last call)

services: workmen.biojs.net, proxy.biojs.net
There is no js api or framework, which is due to the fact that there is no core at the moment. After half an year without a core my experience is that we should enforce more standards and even think about creating an essential core lib.

On January 19, 2015 2:43:06 PM CET, "Devasena Inupakutika (di1c13)" [email protected] wrote:

@greenify @daviddao In the process of working on notes for
documentation guidelines, I would need clarification on certain terms
to be used. One or two examples for these would help in this case.

1. BioJS components
2. Packages (Packages are same as components?)
3. APIs available in BioJS (from the discussion in the last call)

---

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

[timruffles]

enforce more standards

I still think embrace and improve the best way. Most people contributing
will not be first and foremost programmers. Once they've contributed we can
detect issues and suggest changes, and can encode standards in the docs
(e.g don't conjoin data-fetching with visual work, accept DOM els not CSS
selectors etc)..

and even think about creating an essential core lib.

What is specific to bio visual components?

On Tue, Jan 20, 2015 at 5:41 AM, Seb [email protected] wrote:

Sorry for the late response.

1. BioJS components

Biojs-vis-msa, biojs-io-fasta

1. Packages (Packages are same as components?)

Yes. Basically a npm package is a biojs package. However at least I
differentiate between visualization components and non visualization -
maybe we could define a component as a package with visualization?

1. APIs available in BioJS (from the discussion in the last call)

services: workmen.biojs.net, proxy.biojs.net
There is no js api or framework, which is due to the fact that there is no
core at the moment. After half an year without a core my experience is that
we should enforce more standards and even think about creating an essential
core lib.

On January 19, 2015 2:43:06 PM CET, "Devasena Inupakutika (di1c13)" <
[email protected]> wrote:

@greenify @daviddao In the process of working on notes for
documentation guidelines, I would need clarification on certain terms
to be used. One or two examples for these would help in this case.

1. BioJS components
2. Packages (Packages are same as components?)
3. APIs available in BioJS (from the discussion in the last call)

---

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

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

[DevasenaInupakutika]

@greenify @timruffles Thanks very much!

maybe we could define a component as a package with visualisation?

This may cause confusion?

From FAQ and tutorials, component is a sub-set of package.
Package could be a visualisation component or not which will be selected by developers while creating their own BioJS package. (as it is asked when doing slush biojs inside the new package directory and answering yes to the generator)

Hence, how about just using Package for everything?

[ljgarcia]

Hi,

On 2015-01-20 16:22, Devasena Inupakutika (di1c13) wrote:

@greenify [1] @timruffles [2] Thanks very much!

• maybe we could define a component as a package with visualisation?

Not sure that is a good idea, because components do not have
necessarily to be visualizations. They can be parsers.

I would say "component" is a BioJS concept. A BioJS component is (right
now at least) an NPM package. A BioJS component should fit in BioJS,
i.e., it is written in JS, follows BioJS recommendations, is it about a
bio-thing, etc. A component should behaves as a unit responsible of
itself, so developers using it should be able to instantiate it, use it,
and destroy it. It is a piece of code (possible with multiple modules)
that solves a problem, could be a simple or complex problem, but a well
defined problem/situation/need. For instance, visually align two
proteins.

Now, I have mentioned also "module", well, modules are small pieces of
code that address one single thing at a time. They by itself may not be
useful, their value comes when they are used to get something bigger
done, a component. For instance, visualizing a ruler, and such a ruler
can be use in the protein alignment in order to facilitate users to
locale a position in the the sequence when not enough space for each
amino acid in the screen, something like that.

In any case, wait for Seb and Tim to see what they say.

This may cause confusion?

From FAQ and tutorials, component is a sub-set of package.
Package could be a visualisation component or not which will be
selected by developer while creating their own BioJS package. (as it
is asked when doing slush biojs inside the new package directory and
answering yes to the generator)

Hence, how about just using Package for everything?

Reply to this email directly or view it on GitHub [3].

Links:

[1] https://github.com/greenify
[2] https://github.com/timruffles
[3] #20 (comment)

[wilzbach]

I would say "component" is a BioJS concept. A BioJS component is (right
now at least) an NPM package. A component should behaves as a unit responsible of
itself, so developers using it should be able to instantiate it, use it
Modules are small pieces of code that address one single thing at a time.

I really do like your explanation :)

[DevasenaInupakutika]

@ljgarcia @greenify That makes it clear now. Thanks both!