On 1/11/2024 12:01 AM, Moshe Dicker wrote:
I should not that I'm only being critical to improve.
The docs are well written, it's just disorganized.
Something I've learned over the past 47 years of reading computer
documentation is that _no_ documentation is "perfect" - especially not
for everyone.
All documentation is a compromise.
Different people have different ways of reading and understanding
written material. There is no "one right way" to write or organize a set
of manuals. The best you can hope for is to create docs that are
complete, materially correct, and internally consistent.
I have also learned through the years that it's _me_ that needs to adapt
myself to the different styles of documentation available. Yes, I have
preferences for certain styles. But, I also recognize that not everyone
reads and processes information the same way I do. I have no doubt that
_you_ would find it an improvement to change the docs as you describe.
However, I would suggest that you not try to sell the idea as being
objectively true for everyone and that it's "obviously better".
Me? Personally, I have an extreme dislike of docs embedded in code. When
I want to read the code, I want to see the code - not a full set of
reference information that I have to wade through - and ignore - while
I'm trying to find the information I want to see.
I want the code to be free of any clutter that can be better stored
elsewhere.
Likewise, I greatly prefer docs that go well beyond just being an "API
reference". I find sites for libraries showing nothing more than
Javadoc-style pages to be virtually useless to me when I'm first getting
started.
I have long maintained that I am more than twice as productive using
Python than I am in any other language - and part of that is the quality
of the Python docs. I always seem to be able to easily find what I'm
looking for.
In my opinion, the Django docs are close - but not quite as good - as
the Python docs. There are a couple of specific topics where I do find
myself thinking "Where is that documented?" and have to search for it.
It's not that I think they're in the "wrong" place, but it's probably
not where _I_ would have put that information. But that's ok, I probably
should just bookmark those pages...
So no, I'd be a strong -1 to any recommendation suggesting that
docstrings be used to clutter up the code.
--
You received this message because you are subscribed to the Google Groups "Django
developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-developers/fcf2a34e-fb7c-4b9f-af73-6096c324af3c%40comcast.net.
