[Bioperl-l] http://www.bioperl.org/wiki/Bptutorial.pl

[Chris Fields]

...

> We certainly wouldn't want to try to maintain two copies, one POD one in
> wiki. That would be the worst of all options. One option that hasn't been
> mentioned yet is to keep maintenance of that in POD in the distro (leaving
> the cool runability alone), and then flag that document as unchangeable in
> the wiki with a note on top "Maintenance of this document is done in POD
> in the distro. Submit POD patches to bioperl-l and we'll re-post an
> updated copy to this wiki."
> 
> Just a thought.

There are probably three schools of thought on docs: those that like nice
docs with links within and beyond BioPerl (hence the wiki), those who like
including docs with the distribution, and those that would like both.  The
latter would be nice but isn't realistic unless we can come up with a way to
sync changes between the wiki and CVS those docs we want to include with the
distribution w/o too much trouble.  I'm in the first school of thought since
rich text with links is better and more informative than plain text any day.
It might be a very small school though...

> > - What do we do with the script part of bptutorial.pl? It certainly
> could be
> > excised and put into the examples/ directory, for example, but this
> would
> > break a few of the paths that are being used.
> 
> /README says this:
> 
>  scripts/    - Useful production-quality scripts with POD documentation
>  examples/   - Scripts demonstrating the many uses of Bioperl
> 
> I'm personally not clear on the difference. Little stuff should start in
> examples/ and graduate to scripts/ once they've matured?
> 
> Is the doc/ tree being abandoned?

Most docs have been moved over to the wiki, which generates nicely formatted
docs for printing.
...

> Does all that stuff officially live in and is being changed in the wiki,
> never to return to the distro?

It's easier to add changes in the wiki and add markup, links, etc.  Much
richer text, so on.
 
> Any reason those empty dirs aren't nuked out of CVS?
> 
> Chris Fields wrote:
> > Jay, looks like there are still some weird formatting issues with the
> > bptutorial wiki page, something which I ran into before when getting the
> > Install docs up for Windows and UNIX (the mediawiki setup thinks 2 or
> more
> > spaces preceding a line denotes code for some reason).  Not much you can
> do
> > in these cases except remove the extra spaces in those spots.  Looking
> good
> > though!
> 
> Sorry, I spent zero time on the whole conversion. I'm not sure what parts
> didn't convert well. I've never done that conversion before, and know
> nothing about mediawiki. I just blindly let Pod::Simple::Wiki do its thing
> then ran off to work. :)

No big deal.  

> Mauricio Herrera Cuadra wrote:
> > I've added a link in the left menu of the wiki. If you think it should
> > point to the Tutorials page instead of the Bptutorial.pl page please let
> > me know.
> 
> Instead of all these competing links on the left, maybe we should have a
> master "documentation" page linked on the left cascading like so?
> 
> Documentation  (linked on the left menu)
> - Quick start
> - FAQ
> - HOWTOs
> - Tutorials

Okay, though Mauricio may know a bit more on how/if this can be done.
Mauricio?

> (What's the conceptual difference between a HOWTO and a tutorial?)

I believe the reasoning is along these lines: HOWTO's are focused in on
specific areas (graphics, trees, BLAST report parsing, etc) and thus usually
has greater detail. The tutorials are more broadly based (sort of a general
bioperl HOWTO).  The only exception is the Beginner's HOWTO, but even that
has additional information over the tutorial (at least it did the last time
I looked at the tutorial, which has been a while).

> It's hard for me to dive into a wiki lifestyle for the huge documentation
> pillars since it can't ever get back into the distro... (can it?)  Small,
> throw away stuff is great for the wiki, but huge, established, thoughtful,
> long documents should be left in the distro? Present (and searchable) on
> the wiki but static?

Hence the problem we face now.  It is something we need to really look into
before adding too much more to the wiki.  IMHO, I think we should have very
little information directly in the distribution itself since it's already
quite large.  It's almost as easy to have a bare-bones INSTALL file, which
would point to the wiki for additional information.  But I may be very much
alone in that train of thought ; >

> Why isn't the short "Current events" just listed on the top of the "News"
> page?

Don't know.
 
> Sick of my endless questions yet? -grin-

Not really.

cjf

> j
> 
> _______________________________________________
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioperl-l