Ned Batchelder writes:
> I feel like we are missing a key element of Riccardo's point:
> "without editorial guidance." Changes are being made without
> first having an agreement about what the tutorial should be.
That's really unfortunate. But there also ought to be an editorial
activity, s
On 11/9/20 2:25 PM, Raymond Hettinger wrote:
On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev
wrote:
My concern here is that if you start removing or simplifying some
"too-difficult-for-a-tutorial" bits of information on an occasional basis, and
without too much scrutiny or
I think when Riccardo said "The PEPs are the worst," he meant that PEPs
do not work well as documentation for features, because it was not their
purpose. PEPs are designed to be proposals, and then summaries of
decisions. I agree with him that linking to PEPs should be for
supporting informat
On Thu, Nov 12, 2020 at 8:49 PM Guido van Rossum wrote:
> The correct place for the docs for __cause__ and __context__ is in the
> section in the library reference about exceptions. There's quite a bit
> about them there already. That's where the tutorial should link as well.
>
> And now I ask yo
The correct place for the docs for __cause__ and __context__ is in the
section in the library reference about exceptions. There's quite a bit
about them there already. That's where the tutorial should link as well.
And now I ask you to stop complaining (your "the PEPs are the worst" does
not help
> There is value in having non-trivial coverage of the language. When people
> ask how
> __cause__ works, we can link to the tutorial.
I don't necessarily agree with the rest, but I think this is very important -
at least, in the
current situation. Maybe in the future we will be able to rear
> I suspect that future documentation will have "How Tos" being more often
> written to cover more technical topics in detail. These more standalone
> "How Tos" can then be linked to from contents and search pages.
Indeed. Take for instance the most recent addition, regarding special
parameters
Hi Kyle,
> ... I think that we should use the
> guideline of: "Is this useful information in 95% of real-world use cases or
> does it have a strong niche purpose that will be useful at some point for
> significant number of Python users?" If not, my opinion is that it should
> be removed ...
I'm
Inada,
as I said before, mine was more a general consideration than a criticism of a
particular change (let alone a particular committer!).
> But the tutorial isn't a "special attribute showcase".
> It doesn't cover all special attributes and describe how Python
> interpreter use the special att
On Tue, Nov 10, 2020 at 8:07 AM Mats Wichmann wrote:
> On 11/9/20 12:46 PM, Mike Miller wrote:
> >
> > On 2020-11-09 10:44, Simon Cross wrote:
> >> That's quite subjective. Personally I prefer a more complete tutorial
> >> which explains many details so that I don't immediately run into
> >> fund
On 11/9/20 12:46 PM, Mike Miller wrote:
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial
which explains many details so that I don't immediately run into
fundamentals I don't understand when I start using what I've learned.
K&R was ve
We'll be making an announcement in a few weeks asking folks to apply for
the workgroup. The workgroup will be at most 20 people with the goal of
having significant representation (25% to 50%) of individuals who are
educators and documentarians. One goal of the workgroup is to set
documentation prio
On Tue, Nov 10, 2020 at 03:33:06AM +1100, Chris Angelico wrote:
> If that were to happen, what I'd prefer is to cut lots of info out of
> the *TUTORIAL* and make a new document called, say, *Python Advanced
> Techniques* or something, which could still have the narrative style
> but would be aimed
The current version tutorial *already* isn't written in my voice any more.
I don't want to argue about the rest but I disagree with a lot of your
other bullets too.
On Mon, Nov 9, 2020 at 11:28 AM Raymond Hettinger <
raymond.hettin...@gmail.com> wrote:
>
>
> > On Nov 7, 2020, at 9:51 AM, Riccardo
On Mon, Nov 9, 2020 at 1:29 PM Raymond Hettinger
wrote:
> * FWIW, I've closely monitored the bug tracker daily for almost two decades.
> We almost never get a user complaint that the tutorial is too advanced. For
> the most part, it has long been of good service to users. Almost certainly
>
+1e6 + 5j # :)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python
for what it's worth, i would really like to be part of the docs workgroup.
if anyone confirms it's open, count me in!
On Mon, Nov 9, 2020 at 1:38 PM Guido van Rossum wrote:
> Do you want to join the docs WG? IIUC it’s open to new members. (Carol?)
>
> On Mon, Nov 9, 2020 at 08:34 Chris Angelico
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial
which explains many details so that I don't immediately run into
fundamentals I don't understand when I start using what I've learned.
K&R was very popular, so I don't think I'm alone i
> On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev
> wrote:
>
> My concern here is that if you start removing or simplifying some
> "too-difficult-for-a-tutorial" bits of information on an occasional basis,
> and without too much scrutiny or editorial guidance, you will end up
On Mon, Nov 9, 2020 at 6:38 PM Chris Angelico wrote:
> The name "tutorial" definitely screams "thing you should go through
> first". It shouldn't have to teach you everything. Keep the tutorial
> simple.
That's quite subjective. Personally I prefer a more complete tutorial
which explains many det
On Tue, Nov 10, 2020 at 3:38 AM Guido van Rossum wrote:
>
> Do you want to join the docs WG? IIUC it’s open to new members. (Carol?)
>
Me personally, or members of this conversation in general?
My life is a bit too chaotic at the moment to take on more
responsibilities, although I might reconsid
Do you want to join the docs WG? IIUC it’s open to new members. (Carol?)
On Mon, Nov 9, 2020 at 08:34 Chris Angelico wrote:
> On Tue, Nov 10, 2020 at 3:19 AM Simon Cross
> wrote:
> >
> > I really enjoyed learning from this "user manual with a strong
> > narrative component" so I would personall
On Tue, Nov 10, 2020 at 3:19 AM Simon Cross
wrote:
>
> I really enjoyed learning from this "user manual with a strong
> narrative component" so I would personally like to see it stay even if
> a new tutorial is created for a different kind of audience.
If that were to happen, what I'd prefer is t
I really enjoyed learning from this "user manual with a strong
narrative component" so I would personally like to see it stay even if
a new tutorial is created for a different kind of audience.
___
Python-Dev mailing list -- python-dev@python.org
To unsub
It looks like the tutorial has already evolved into something close to a
user manual (with a strong narrative component). This definitely sounds
like something for the docs workgroup!
On Mon, Nov 9, 2020 at 2:02 AM Kyle Stanley wrote:
> Rather than trying to specifically transform the existing t
Rather than trying to specifically transform the existing tutorial into a
guide exclusively aimed at beginners, I think that we should use the
guideline of: "Is this useful information in 95% of real-world use cases or
does it have a strong niche purpose that will be useful at *some *point for
sig
On Sun, Nov 8, 2020 at 8:17 PM Inada Naoki wrote:
> OK. Since checking all mails in the long thread is tedious job, I will
> pick some up and leave a comment in the b.p.o.
>
Personally, I think that just linking to the python-dev thread in bpo
(and/or PR) is adequate for most cases, especially i
On Mon, Nov 9, 2020 at 9:20 AM Terry Reedy wrote:
>
> >
> > Again, I did it following not only a brief exchange on the b.p.o., but
> > also long discussion in Python-dev.
>
> When I act on an issue on the basis of a pydev discussion, I hopefully
> remember to avoid such after-the-fact concerns by
On 11/8/2020 5:51 PM, Inada Naoki wrote:
On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev
wrote:
Rather, I am slightly concerned about the method in itself - that a deletion
may occur following only a brief exchange on the bug tracker.
Again, I did it following not only a
On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev
wrote:
>
> Hi Inada,
>
> > Note that the discussion not only in the b.p.o thread, but in this
> > mailing list too.
> > Please read this long thread.
>
> I have, but I don't know if I want to step in...
> I do have, indeed, opinions
Hi Inada,
> Note that the discussion not only in the b.p.o thread, but in this
> mailing list too.
> Please read this long thread.
I have, but I don't know if I want to step in...
I do have, indeed, opinions (and some expertise) on the matter, but
I've never really thought about it in depth...
Hi, Riccardo.
I'm who removed the __cause__ from tutorial, and I had translated
Japanese translation of official Python document hard.
On Sun, Nov 8, 2020 at 3:07 AM Riccardo Polignieri via Python-Dev
wrote:
>
> This morning I noticed this new commit, referring to bpo-42179: "Remove
> mention
32 matches
Mail list logo
