[Tutor] Documentation concerns.

[Jorge Godoy]

Magnus Lyck=E5 <magnus@thinkware.se> writes:

> At 09:04 2003-05-24 -0300, Jorge Godoy wrote:
>>I agree with you on how good it is to have books to do serious
>>development. We in the southe hemisphere,
>
> Oh, I though UNC was in North Carolina. :)

I'm sorry. I have some projects there (I'm on the LDP staff) and their
email system is VERY reliable. I use it, saving IEEE's address for
engineering related stuff and my company's address for commercial or
commercially interesting communication. :-)

> So you have to trade time for money... $70 seems very much though.
> Python is a Nutshell, which I haven't read, but have heard very good
> things about, is $21.50 + shipping at bookpool.

Good to know that.=20

> If you buy a number of books, shipping costs will not be such a big
> part of the cost. Try to get together with some other people so that
> you can buy ten books or so at the same time, and you will get a
> much lower price than through most other channels.

I want to do that, but then I have to find those people :-)

> That makes your complaints about lacking information a bit
> surprising.

I'm not arguing about the lack of existing documentation. I'm arguing
about the lack of existing documentation *within* the module.=20

I've sent an example on the message you crossposted. I hope it makes
my point clearer. If not, I can keep on trying to explain until you
people say that I should stop trying it. :-)

> There aren't any ads in the python documents either... As both Alan
> and I pointed out, there are several disadvantages with this. For
> documentation like the wxPython docs that mainly consist of showing
> the method calls, it would probably be better to use something
> generated from code, particualrly considering the problem that
> project has in keeping the docs updated. Also, consider all the
> questions Robin Dunn has to answer every day, it's clear that
> wxPython need documentaion which is on a completely differnt level
> than to describe the details on what parameters to provide for each
> method call etc.
>
> As I've said, the source code structure might not match the
> best structure for describing the code.

It shouldn't describe everything but it should be enough to get a
working example or a better undertanding on how to use the available
stuff.=20

It shouldn't be a tutorial.

> I think we should make certain that we always get docs with our
> code, but I can't see that the exact organisation of docs and source
> code is an important issue.

This lead us back to the new point of view with new people, I think.=20

> It seems that the current approach is still to have the bulk of docs
> in separate files and just small hints in the soure code.

If it's possible to make something that read the documentation from
this other place and make it standard, it would be enough. Actually,
it would make things even better since people would be allowed to
exclude the docs if they want (the embedded case I talked about) but
they can't talk about the lack of docs if they do that.=20

> I'm sure you can write a nice utility that will get the right
> information quickly without too many key-presses.

Not for each and every module... Unfortunately. I'm looking for a more
generic solution.

I'm a lazy guy and this is why I write programs: they can do my job
while I keep reading emails :-)

>>I be you will :-)
>
> Freudian slip? ;)

Heh... Got me on my own joke.

> I think it would be great to have some way of integrating the docs
> for site-packages in some common structure. Both for indexing and
> for searching.

Me too. Maybe we can come up with some kind of proposal for that.=20

> But reStructuredText is not XML. It's less verbose and more readable
> than Latex in my opinion. Have you used it?

I've just used docstrings... For more verbose docs I usually use LaTeX
myself or some kind of XML (I'm used to use DocBook).=20

> Startup delays are annoying. If you run several hundred small tests
> and every test has a startup cost, you won't want to run the tests
> as often as you should.

On the other hand, with better docs I should develop faster and with
less mistakes on my understanding of the docs.=20

> No we should not. The introspection facilities and dynamic nature of
> Python is a big advantage. Stripping the code will give us much less
> to introspect.

I can't, yet, comment on that. I take your word on it.

>> > In general I think the Python developers are open to improvements,
>> > but they are not able to put a lot of time into this. They do depend
>> > on help from the community.
>>
>>:-)
>>And then they should offer the community more resources.
>
> I'm not sure what you mean. What is it that you need and don't have?

Means to reach them and propose changes.=20

But, with all this discussion, I think I had that too. So this problem
is solved.

> Python is obviously more of a collective effort, and it
> has a fairly clear structure and reasonable information
> about how to contribute. See for instance
> http://www.python.org/dev/
>
>>:-) You're not a newbie, this is why. For website and articles I'd
>>take a look at
>>HTMLgen(http://starship.python.net/crew/friedrich/HTMLgen/html/main.htm=
l).
>
> Really? It's not been in development for years. I used it to build a

Yep. I saw that too... But it seemed to be the simplest thing out
there. I was anxious to have something that solved this fast. I am
studying which module I'm using to replace TT2... (And it accepted
what I had out of the box.)

> web site a number of years ago, and I ended up building something
> reStructuredText-like on top of it. reStructuredText is a much
> easier tool, and you don't need to worry about programming to get
> decent looking documents in both XHTML and PDF from the same simple
> source.

I'll look at it. If I can plug my existing documents only with minor
changes it will be very good.

I'm trying to see what tasks I can switch from Perl to Python and
which of these are easier to me and my team.

--=20
Godoy.    <godoy@metalab.unc.edu>