[Rd] suggestion for R >= 3.0: computer-readable CHANGELOG

[Ted Byers]

On Fri, Apr 17, 2009 at 10:12 AM, Dirk Eddelbuettel <edd at debian.org> wrote:
>
> On 17 April 2009 at 09:05, Duncan Murdoch wrote:
> | That would be a waste of time.  People don't use the package
> | documentation schemes that are in place; why would they use a new one?
>
> Because of scattered documentation and lack of best practices?  Many things
> are possible with R and packages, how many are really done consistently?  I
> think this points to a need for better examples, better docs, and better
> package checking tools.
>
Best practices?  Such things exist, and I am sure software engineering
students are routinely introduced to them these days, but at the same
time, I have seen projects where they were ignored and even where
management told their engineers to not waste time documenting
anything.  :-(   Of course I circumvented such direction by embedding
my 'documentation' as comments within my code so that anyone who is
assigned to maintain the code would know, from my comments and coding
practices I both used and taught to my juniors there, how it all
works.  I remember some of my old FORTRAN code where there were more
lines of comments documenting everything for other programmers than
there were lines of code; all in one file so the programmers using the
file would not have to look far to find the information they needed.
Not as good as the now usual UML documentation, but better than
nothing and essential in a project involving more than half a million
lines of code.

No matter how good you get, there is always a need for more, and
better, examples, documentation and tools.

> I happended to have the same discussion via email last night with Brian
> (CCed) who wanted to see NEWS / Changes in my CRANberries RSS feed for CRAN.
> I suggested pretty much what Philippe suggested in the first post in this
> thread --- with one addition.  I think we need a test in R CMD check that
> emits a warning if there is no inst/NEWS or inst/Changes or inst/Changelog.
>
This reminds me of a tool I encountered years ago (called aegis) that
could be configured to not permit committing new code to production
codebase unless there were unit tests for it, ideally an integration
test or two, and that prior to commitment the entire build, including
the new code, passed all existing tests for the project.  A wonderful
tool for ensuring new code didn't break things!  But it works only is
used as intended.  After all, it would be trivial to write a dummy
test that always passes regardless of what the application code really
does.

If you really want your developers to use some minimalist list of best
practices, you really have to do two things.

First you have to be able to demonstrate that they will make life
easier for the developer.   I never met a developer who would spend
even a few minutes on a task for which they did not see a significant
benefit.  Even if you made it a condition of employment, you'd see on
half hearted, sloppy efforts at tasks for which they see no
significant benefit.  Since time is so precious, an intermediate
programmer is not likely to write usable documentation of his code for
a junior developer that has to follow in his footsteps.  Yes, as a
condition of employment, he'll write something, but it will be terse,
and next to useless for anyone who didn't write the code.

Second, you have to make it relatively easy to do.  No matter what the
payoff for the developer, he won't do it if the only way he can get it
done is to stand on his head eating peanuts and spitting the waste
shells into a garbage container 5 meters away while typing with his
toes, blindfolded.  It isn't going to happen.  And it can get worse in
that I have seen software houses that provide services to develop
custom software and they have a vested interest in making
comprehension of their code so difficult that their clients have no
option but to go back to them for maintainance and upgrades if they
want it in a timely fashion.

There are reasons why software developers don't use documentation
frameworks that are available to them, and I have seen some larger
software houses that have essentially capitulated to such human
behaviour and hired documentation specialists.  Who is best to develop
documentation for a given product: the engineer who developed or an
educator who has been assigned to teach people how to use it?

I can both appreciate the original request and understand why people
behave in a way that resulted in Duncan saying it is a waste of time
because people don't use package documentation schemes that are
available, and if I were managing a project I'd likely share his
frustration with it.  I certainly don't envy anyone trying to address
this issue.

Good luck.

Ted