On Wed, Sep 3, 2014 at 1:00 AM, Antonio Terceiro <terce...@debian.org> wrote: > Hi Caitlin, > > First of all, thanks for all the effort you have been putting in the > Ruby packages. It is really appreciated, and you already a valuable > member of our team. :)
Indeed, thank you! > On Thu, Aug 28, 2014 at 03:29:48PM -0400, Caitlin Matos wrote: >> >> Adding and generating this documentation is really very easy (you're not >> writing the documentation, just installing it). Therefore, I think this >> could be a great way for newcomers to contribute to Debian. I would create a >> tutorial on the wiki on how to edit debian/rules to build the documentation. >> I would also go through the packages and label them with "gift",[2] so they >> would appear via the how-can-i-help application.[3] >> >> In total, what I'd like to do is: >> * Comb through the packages and figure out which ones have documentation >> available but not being installed via HTML >> * File a bug against these packages, using the usertag 'ruby-doc' (or >> similar) >> * Label appropriate packages/bugs with the usertag 'gift' >> * Create a tutorial on how to include documentation I think this would be great! A particularly good use of the gift usertag. >> The one downside I envision is an influx of RFS and Alioth access requests, >> which is good or bad, depending on your perspective. It is definitely a genuinely good thing. I seriously doubt that there will be a massive unmanageable storm of new contributors. >> As I am not a DD, I cannot help with this part. Have you joined the New Member process [1] yet? You probably have a few advocates on this list already (you need one). >> I would like some feedback as to whether this is a worthwhile initiative >> and/or other ideas. Please discuss over the mailing list, or during the Ruby >> BoF on Friday. > > To be very honest, I don't think we should do that. I have 3 issues with > it: > > 0) adding a -doc package for each source package will add a burden to too many > people. This will use: > > - time from 1 person to update the packaging > - maybe time from 1 person to review and upload (in the case of > sponsored uploads) > - time from 1 ftp-master to accept the upload (due to the new binary > package) > > 1) adding a -doc package for each source package will clutter the > archive unnecessarily in my POV. For most(?) packages the documentation could probably go into the main binary package instead of a separate -doc package. > 2) the HTML documentation produced by rdoc (or yard, for that matter) is > too big. I just tried building rake from git, and the and the -doc > package has a bunch of stuff (fonts, js files etc, images) that will > probably be duplicated in every other -doc package. Which are probably in MRI source somewhere, or in some other package e.g. libjs-jquery. > ------------------------------------------------------------------------- > > Related to 1) and 2): Perl packages include documentation (manpages) in > the main package and that hasn't been a problem because the format is > sane, doesn't waste space and don't duplicate stuff across packages. > > I think we should not add -doc packages, and before we even think about > including documentation in Ruby packages, we need to find a solution for > size issue. Where do you think the line for oversize docs are? How many packages have massive docs, like rake? > Another alternative would be to work on something that would work for > all packages at once. For example, we could have a service that would > generate documentation from all source packages, and then a single > package in Debian that would download documentation for all installed > packages (think something similar to apt-file) for offline usage, plus > an option for building/installing documentation from local source > packages. But this would also take up people's time, discussing, coding, maintaining. Although it might be beneficial in some ways, I like the idea of attracting new contributors that Caitlin presented in the beginning of the thread. Especially if we don't see rdoc/HTML documentation as something crucial, this can evolve over time. [1] https://nm.debian.org/public/newnm -- Per -- To UNSUBSCRIBE, email to debian-ruby-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: https://lists.debian.org/cabyrxsseet2gorar-wy+qpoxxrbczjnd5_vokh2sztyhw+i...@mail.gmail.com
