State of developers-reference
I'm quite concerned about the state of developers-reference.
- I've basically been the only active maintainer for over a year.
- There are many open bugs, about things that should really be fixed or
added in dev-ref, but I don't have time to address them (I'm doing
"please provide a patch and I'll integrate it"-maintainance).
- There are more and more places where documentation about Debian
development is being published: wiki pages, blogs, d-d-a, etc. While
it might be good to keep developers informed, it's clearly not a good
thing on the long term: you end up having to google for many d-d-a
We really need to do something about this. Documentation about Debian
development plays an important role in the way we are perceived as
"welcoming" to newcomers. Our procedures are getting more and more
complex (use of packaging helpers like cdbs and dh7, use of VCSes), but
our documentation doesn't improve.
First, we need to decide whether we want to continue to maintain
developers-reference. We could simply decide that it's deprecated, and
use a set of wiki pages to document our procedures. I see some value to
a (mostly) self-contained documentation, but, if it helps getting
contributions from more people, we could simply move to wiki.d.o. (or to
a ikiwiki instance). I'm not a big fan of wikis, so I wouldn't continue
to "maintain" dev-ref, but I'm open to the idea.
If we decide to continue to maintain developers-reference, we should all
participate. I'm not asking everybody to become co-maintainers (some
help is probably needed, and would be welcomed, but I don't think that
the main problem is here).
- When announcing a change of procedure to d-d-a, or information that is
useful on the long term, prepare a patch for dev-ref at the same time.
It doesn't need to be in docbook-xml (plain text or html would do).
- When doing talks about something at Debconf or at another conference,
take the opportunity to review and improve the corresponding dev-ref
section. (That applies to the i18n chapter of dev-ref, which is
apparently badly outdated).
- Contributing to dev-ref could become a part of the NM process. We
already have a "fix two RC bugs" question. We could have a "fix two
dev-ref bugs" one.
| Lucas Nussbaum
| firstname.lastname@example.org http://www.lucas-nussbaum.net/ |
| jabber: email@example.com GPG: 1024D/023B3F4F |