[Biopython-dev] Problems with the tutorial

[Tiago Antao]

Hi Vincent, Peter and all,

On Thu, 14 Jan 2016 08:06:19 -0700
Vincent Davis <vincent at vincentdavis.net> wrote:

> > Was any of this version of python specific?

I just tried with 3.5, but I strongly suspect most of these are not
specific. I have noted all the cases that I believe are specific in the
reported issues.

> Good question, I have to assume the tutorials worked when they were
> written. My impression is that the issues are not a result of any
> specific cause, like Python 3, rather a result of the tutorial going
> stale as the project moved along. I have not been around to what so
> can't really say.


I think this is a fair assessment of the situation. Especially after
having spent quite sometime with the mistakes that I have found. Most
code has worked in the past (actually the vast majority still does!),
but some stuff has just become dated (for example datasets that do not
exist anymore on the web).

> Why have separate documentation/tutorial/cookbook here?

I think the tutorial is a a bit old fashioned in terms of format.
Notebooks are all the rage, and the future.

I do think that it is inevitable that different mediums have different
contents. As I think I told you privately, I believe that the tutorial
is just a first step for the notebooks: The content (especially the
text) does not lend itself very well to a notebook format.

My plans with the notebooks (up for discussion, of course) are to
diverge them after the tutorial conversion is fully working. The idea
is to have a text and code that is more aligned with the notebook
metaphor.

> What I think would be cool. Static Jupiter notebooks as documentation
> (think nbviewer http://nbviewer.ipython.org/) with a link to launch
> the notebook into a Live executable jupyter notebook, see:
> https://lambdaops.com/ipythonjupyter-tmpnb-debuts/  Or just export
> as .py or more boring pdf/html
> Since I think this would be cool I have been working to making this
> happen, Any thoughts?

I think this is a good idea. I believe that the most used format will
be the notebook. The static version would be for reference. The
launched notebooks the platform where people could learn by doing (and
a great platform for biopython-based courses). The PDF format is a bit
of a offline content.
Code extraction to .py can be useful also.


> I have been busy with a few other projects recently, hope to get back
> to this soon.

Same here, but we have been slowly advancing. I think the notebook
version is now at least as good as the tutorial (as it has less
mistakes).

Tiago


-- 
"While I may be sending this email outside my normal office hours, I
have no expectation to receive a reply outside yours" - @tomstafford