Re: Proposed new initiative: include HTML documentation
On Wed, Sep 3, 2014 at 1:00 AM, Antonio Terceiro <terceiro@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
Reply to: