Daniel - On Tue, May 4, 2010 at 4:35 AM, Daniel Carrera <[email protected]> wrote:
> Derek Lamb <[email protected]> wrote: > > > > Anyway, I think I can improve the wiki. > > > > you suggest copying several PDL docs into the wiki. I'm not sure > > that's a good idea right now, mostly because those documents are > > present in the PDL source code (for example, see Impatient.pod). > > This makes it easy for these documents to start diverging, making for > > a maintenance nightmare. Linking to the relevant online docs is a > > good idea, however--those are updated pretty regularly. > > > Linking is fine. Finding the right docs is more important than making them > consistent. > > > In fact, I just updated the online docs. Look for PDL::Guide in the > > manuals section. This may be what you are looking for . A link to > > that from the wiki might be a good place to start. > > Ok, I found it: http://pdl.sourceforge.net/PDLdocs/Guide.html > > Hmmm... This document is already *much* better than the proposal I wrote. > This is a perfect example of PDL having good documentation but it being > difficult to find. > The Guide states that it started life back in January, but in fact I just added it to the git sources last week. It is a *very* new doc. I'd like to see it promoted to a higher place in the documentation hierarchy as well and I wrote with the intention of having it go under PDL.pm's documentation. (Aim high, right?) Since PDL.pm is a really important module, I didn't want to make such a major change without getting some comments first. You caught it in a state of flux. I don't know what to suggest. This page is *exactly* where a new user should > start. No question about it. That was my aim, so I'm glad to see it's working well for you. Please let me know about any changes that would be helpful for making it a better document! > So I wouldn't just want to add a link some place where nobody will see it. > Indeed, I'd love to just copy this to the wiki front page and make small > edits. But earlier you warned against copying because of the maintenance > cost. > See my comments below. Well, at a *minimum* I would say that the 'Documentation' link on the PDL > front page should point directly to PDL::Guide. > I agree, though I am probably biased. :-) > But what do we do about the wiki? What's the purpose of the wiki if all the > documentation is in POD? Unless something changes, the wiki ends up either > hiding the excellent PDO documentation, or else, competing with POD and > dividing the effort. Not good. > > I fear that this is already what started happening. The wiki has useful > pages that should be part of any PDL guide. So the information is already > scattered. > I have not made up my mind as to what role the wiki should play. On the one hand, it's a really pretty face to the wider world and newcomers will feel comfortable with it. It's also supposed to be easier to edit. On the other hand, the Perl documentation tradition is to use pod, as reflected in the wonderful functioning of CPAN and Padre's help (btw, the Padre help formatting just broke on my most recent Ubuntu upgrade). In all, you can write documentation for PDL by (1) editing the wiki, (2) editing or creating pod, and (3) writing demos. The latter two are integrated nicely into the perldl shell. The pod is also hosted online at http://pdl.sourceforge.net/PDLdocs/ and integrates nicely with Padre and not-so-nicely with CPAN (an area that needs work). Now you can probably understand why I changed my focus from wiki editing to working with pod: contributions to pod will show up in many places, whereas contributions to the wiki only show-up on the wiki. Also, if you spend much time combing through the PDL documentation, you'll find that multiple people have made attempts at grand documentation changes. The wiki points to not one but two attempted books that have both been stalled for many years. The wiki itself is stalled with many ideas for pages but no actual documentation. I even have the startings of my own book for PDL on my hard drive. The moral of the story is this: start small. I recommend making small contributions in pod, like my Guide. If we ever get a PDL book out, I believe it will be the outgrowth of many, many pod files pulled together and edited to make a coherent narrative. If history is any indicator, any outright attempt at writing a PDL book will not make it. David P.S. I think the Guide is a pretty fixed target - unless you have suggestions. If you want to update the wiki page with content from the Guide, I think that's probably OK, but be warned: I will probably not keep the two in sync.
_______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
