Hi David,
> 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!
I have ideas, but I'm looking at it from the website point of view. I
would organize it like this:
* Installation
* Migrating from Matlab or IDL.
* Learn PDL
-> Introduction
-> Normal usage
-> Advanced
* Workflow
-> Introduction
-> Normal usage
-> Advanced
* Libraries
-> Introduction
-> Normal usage
-> Advanced
* PDL Cookbook
* Other resources
* Help & Support
* Developers Corner
As you can see, I'm merging your guide and the wiki. This would work
great for the website, but I'm not sure how it would work for POD. When
you wrote the PDL::Guide you were thinking of PDL's internal help.
What do you think? Do you think an organization like this would work as
PDL's internal help?
I think the *ideal* situation would be if the same manual was available
in both the website and in the PDL distribution.
> 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... On the other hand, the
> Perl documentation tradition is to use pod... [The pod] integrates
> nicely with Padre ... 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.
Indeed. I understand completely. I don't know what to suggest.
Personally I would be happy to use POD. But I realize that the wiki
lowers the barrier to contribution.
How about if you used the wiki to work on documentation and then
converted it to POD? As long as the wiki page doesn't have any fancy
layout or graphics, the conversion should not be problematic.
On the other hand, if everyone is using POD and nobody is using the
wiki, then why change? As I said, I am willing to use POD if that's
what everyone else prefers.
Anyway, what do you think of the wiki-to-pod conversion idea?
> 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.
Indeed. I noticed those. It doesn't give a good impression, and it
actually makes the good docs harder to find.
> The wiki itself is
> stalled with many ideas for pages but no actual documentation.
So the wiki is not contributing much then?
Daniel.
_______________________________________________
Perldl mailing list
[email protected]
http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
