A contribution to developer docs #481
Conversation
|
Thanks, this is all good stuff! Would you like me to merge it as-is, or do you feel like making |
|
Oooh... converting it to POD would make a lot of sense IMHO. It would be discoverable from MetaCPAN and readable with a browser, enjoying a table of contents, and links to other places... Maybe some synchronization with https://github.com/PDLPorters/pdl/wiki/Developer%27s-Corner would not hurt either. I'll do that. |
|
Ah, and there's also https://pdl.perl.org/?page=develop (from pdlporters.github.com). Maybe the wiki or GitHub pages would be the best place to present information, and reduce the DEVELOPMENT file to a pointer? Three different places cause synchronization work without much benefit |
|
I agree with the idea of "only one place". I don't know if the wiki is very useful; I'd suggest we suck all the useful info from it into the website/dev docs and turn it into a pointer. That said, I'm open to more specific ideas! |
|
Ok, let's be more specific: Let me first clarify the issue: The DEVELOP file is not that easy to discover. It is mentioned in README.md, but MetaCPAN does not show that information, and on GitHub one must scroll past two screenfuls of directories and files before the Readme even starts. For MetaCPAN discoverability I suggest to create a file Contributing.pod: This file will be picked up by MetaCPAN and linked under the "How to Contribute" navigation item (as of now, not many CPAN modules make use of this). The contents of the DEVELOP file and the github.io page https://pdl.perl.org/?page=develop should be merged and updated. The DEVELOP file should be deleted, and README.md adjusted accordingly. As for the location of the developer documentation: This could be either on pdl.perl.org, i.e. written in HTML, or in the repository under Contributing.pod. Both formats, POD and HTML, are good enough and better suited for guidelines as plain text. I have a slight preference for Contributing.pod, because then it is in the same repository as PDL itself. In any case, the PDL developer page should keep the short content it has and link to detailed developer documentation. |
That module contains several packages, but no own code. The patch adds a list of contained packages and their object hierarchy to the module's POD. I also removed the reference to the dead Tk demo. Adding at least one line of description for each of the packages is yet to be done.
The PDL source tree has a different layout than an installation. Some files are generated from .pd sources, and some renamings are non-trivial (Pnm->Pic). The patch adds a mapping table to the end of the DEVELOPMENT file.
|
Please can you rebase your branch against current You'll see your PR now fails an author test; you've added a file, but not added it to the The reason that location is better for developer type docs is that when changes get made to PDL and PRed, the dev guide can be reviewed alongside it. That makes it a better store for that information than either a wiki or the website, neither of which really get maintained. Removing information from the wiki and the website into one "source of truth" that is maintained is a far better approach. |
|
Sorry, github handling problem here... I updated my fork's master branch using the web interface which is a bad idea. I hope I managed to clean up the history. Not deleting the DEVELOPMENT file in that commit was intentional, to allow easier side-by-side review of the contents of both files - once the content is approved, the deletion is as easy as another commit. Regarding the name of the POD document: I am fine with publishing it as PDL::DeveloperGuide, I'll make a commit for renaming that. Still I think that having a Contributing.pod (or .md) makes sense: This is where MetaCPAN will pick it up: MetaCPAN is the most important place to discover Perl stuff. Yet another file in the distribution is difficult to discover: https://metacpan.org/dist/PDL is a looooong list with a seemingly random distribution of stuff between "Documentation" and "Modules". A short Contributing.pod pointing to the PDL::DeveloperGuide can go a long way. |
|
Why do you think MetaCPAN will pick up the "contributing" file? MetaCPAN talks about a file located at the top with content similar to what I described above. It won't really add any value, and that's not where people would look for a developer guide. It will be fine to link to such from both the main PDL docs, and the PDL "quickstart", but this "contributing" idea is not helpful. The distribution page for PDL lists lots of modules because PDL has lots of modules. There's not anything "random" about it. |
...also do the bookkeeping chores: + DEVELOPMENT has been deleted, pointers to it now go to DeveloperGuide.pod + MANIFEST has been updated accordingly Changes to the content of the DevelopmentGuide: + It is in POD format. To see a nicely rendered vision without a webserver, I recommend the podview tool from the Prima distribution. Like MetaCPAN, podview presents a table of contents which provides a structure which is difficult to maintain in plain text files + The pointers to Git documentation are moved to a "References" section. Git is mainstream these days, no need to start the page with an explanation. The reference section also points to the PDL website and the MetaCPAN entry point.
|
History has been rewritten to squash the two commits on the way to DeveloperGuide.pod into one. |
|
Thanks, this is great! Some notes for the next brave soul who wants to update the shiny new developer guide:
|
Here are two suggestions for documentation to help people getting started with PDL development. I'll probably add more while I get deeper into the code.