[issue33872] doc Add list access time to list definition

[INADA Naoki]

INADA Naoki <songofacandy at gmail.com> added the comment:

Andrés Delfino <report at bugs.python.org>:

>
> Andrés Delfino <adelfino at gmail.com> added the comment:
>
> IMHO, if we deem it useful for users not to expect the time complexity of
> a linked list for list elements access to the extent of adding a comment in
> the glossary, there's no reason it isn't useful to someone who is reading
> the actual list definition.

I didn't deny "it is useful to someone."

I just worry about adding many random notes "useful to someone" in document
"everyone" reads.  It's worse than nothing.

When writing document for wide readers, adding such "useful to someone"
note is bad idea.
We should focus on "important to everyone" or "critical for someone".

Moreover, I don't see the reason why someone would read the list glossary
> entry after reading the list definition.
>

That's why "useful to only someone" information can be noted on glossary,
but no on main document.

I believe glossary entries should be a (rather small) subset of the topics
> they touch.
>

I don't think so. Glossary is the best place to document "no definition,
but used conventionally" word which is not defined in other document

Current glossary has random tips and notes like this.  They don't bother
readers of main document.

I don't think "document in glossary" is not enough reason to add it on main
definition, because it may lead bad S/N ratio.

Of course, if it's very common pitfall for many people, it's worth enough
to note in the definition.

But IList in C# is sequence and LinkedList doesn't implement it. If many
people feel the word "list" implies "linked list", why they choose the name
"IList"?  That's why I think the note is only for someone, not for
 most readers.

So I'm -0.5 on adding it in list definition, and +0 on removing it from
glossary.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue33872>
_______________________________________