...
Post by Jay HannahWe 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...
Post by Jay HannahPost by Brian Osborne- What do we do with the script part of bptutorial.pl? It certainly
could be
Post by Brian Osborneexcised and put into the examples/ directory, for example, but this
would
Post by Brian Osbornebreak a few of the paths that are being used.
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.
...
Post by Jay HannahDoes 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.
Post by Jay HannahAny reason those empty dirs aren't nuked out of CVS?
Post by Brian OsborneJay, 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
Post by Brian Osbornespaces preceding a line denotes code for some reason). Not much you can
do
Post by Brian Osbornein these cases except remove the extra spaces in those spots. Looking
good
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.
Post by Jay HannahPost by Brian OsborneI'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?
Post by Jay Hannah(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).
Post by Jay HannahIt'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 ; >
Post by Jay HannahWhy isn't the short "Current events" just listed on the top of the "News"
page?
Don't know.
Post by Jay HannahSick of my endless questions yet? -grin-
Not really.
cjf
Post by Jay Hannahj
_______________________________________________
Bioperl-l mailing list
Bioperl-l at lists.open-bio.org
http://lists.open-bio.org/mailman/listinfo/bioperl-l