Proposed new initiative: include HTML documentation
Hi all,
I would like to propose some goals and initiatives for maintaining
proper documentation and also supporting newcomers to Debian looking for
ways to contribute.
One thing I've noticed about Ruby packages is that documentation files
are often installed as plain-text when they should be converted to HTML.
This especially includes any documentation with the suffix *.md or
*.rdoc. While Markdown and RDoc markup syntax is generally readable in
its raw format, these should be converted to HTML for numerous reasons.
For one, many of the markup language's features (e.g., pretty formatting
and syntax highlighting) are lost. For another, Debian Policy is to use
HTML.[1]
Also, even if a package does not include any *.rdoc files, many include
RDoc strings. Policy states that additional documentation can be
installed "at the discretion of the package maintainer". Personally, I
believe in having as much documentation as possible available from
Debian and on the user's system. Therefore, I think that these packages
should be running their files through RDoc and including this
documentation in a separate *-doc package.
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
The one downside I envision is an influx of RFS and Alioth access
requests, which is good or bad, depending on your perspective. As I am
not a DD, I cannot help with this part. Therefore, I don't want to
undertake this project without some feedback from DDs (and anyone else).
Note that I would encourage submitting patches to BTS instead of
requesting write-access to the repo, which might ease the burden a bit.
I or someone else would then upload the patches to git and submit RFS
e-mails in bulk to lessen the mailing list traffic.
It would be nice to have this as a release goal for jessie, but it's
probably too late.
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.
Thanks,
Caitlin
[1] https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4
[2] https://wiki.debian.org/qa.debian.org/GiftTag
[3] https://wiki.debian.org/how-can-i-help
Reply to: