[Doc-SIG] What docs should be in the source file?

[Edward D. Loper]

> I think it's relevant.  The question is "how far is the user of a
> module from *some* information on how to use the module?"  Doesn't
> matter if they don't have every article that anyone has ever
> written about the module -- do they have a starting point?

We all agree that *some* information on how to use the module should
be included.. But the question is *what types* of information to
include?  I think that the in-code documentation should tend to be
concise, short, and technical.  It should be light on examples, and
stick to defining individual elements, with a short overview to
describe how the elements fit together.

> If changing the code changes the behaviour of the module so that
> your examples don't work any more, then yeah, you'd better edit
> the examples.  (Scenario: i've changed a method name from foo() to
> spam(), so in my editor i search for ".foo(" to do replacement...)

Often, the consequences of changes on the tutorial-type docs is not
obvious.  Having to think (hard) about whether my changes affect the
tutorials/howtos/FAQs/etc. every time I make a change seems unreasonable.
On the other hand, API documentation is (by definition) local -- it
should be obvious what parts of the documentation need to be updated
when I change the code.

I guess it just seems like, if I were to have tutorials, etc. in the
code myself, I would not be likely to check them every time I make
a change.  And I think that there are many programmers out there who
are lazier than I am.

> It's also harder for me to change foo() to spam() in just the code,
> check in just that part, and say "oh, i'll change the docs later" --
> because i'll be checking in a single file that's inconsistent with
> itself.

I have a suspicion that laziness will win out, and people will just
say "whatever"..  

If the docs are in a different file, I can do a CVS diff to see what's
changed in the code since the last time I updated the docs, and thus
can do updates to the documentation "in batch."

-Edward