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

[Jay Hannah]

Brian Osborne wrote:
> - Do we remove the file bptutorial.pl from the package now? I'd say yes, we
> don't want to have to maintain two bptutorials.

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.

> - 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?

doc/faq        (empty?)
doc/howto      
doc/howto/examples
doc/howto/figs (empty?)
doc/howto/html (empty?)
doc/howto/pdf  (empty?)
doc/howto/sgml (empty?)
doc/howto/txt  (empty?)
doc/howto/xml  (empty?)

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

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. :)

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

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

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?

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

Sick of my endless questions yet? -grin-

j