Message 148711 - Python tracker

Message148711

Author	ezio.melotti
Recipients	docs@python, ezio.melotti, ncoghlan
Date	2011-12-01.08:10:21
SpamBayes Score	1.1363502e-06
Marked as misclassified	No
Message-id	<1322727022.11.0.935606226368.issue13515@psf.upfronthosting.co.za>
In-reply-to

Content
Grouping the common warnings in a "Security Considerations" section sounds OK, but the warnings should still be visible IMHO. In my experience, people: 1) jump right to the doc for the function they are using; 2) read the example and try to figure out how it works; 3) if that fails, they read the text. An inline text with a simple link might then pass unnoticed. OTOH littering the doc with red boxes is far too noticeable. Maybe we should use something in between (e.g. a "lighter" CSS for the warnings or a small warning icon).

Content

Grouping the common warnings in a "Security Considerations" section sounds OK, but the warnings should still be visible IMHO.

In my experience, people:
 1) jump right to the doc for the function they are using;
 2) read the example and try to figure out how it works;
 3) if that fails, they read the text.

An inline text with a simple link might then pass unnoticed.  OTOH littering the doc with red boxes is far too noticeable.  Maybe we should use something in between (e.g. a "lighter" CSS for the warnings or a small warning icon).

History
Date	User	Action	Args
2011-12-01 08:10:22	ezio.melotti	set	recipients: + ezio.melotti, ncoghlan, docs@python
2011-12-01 08:10:22	ezio.melotti	set	messageid: <1322727022.11.0.935606226368.issue13515@psf.upfronthosting.co.za>
2011-12-01 08:10:21	ezio.melotti	link	issue13515 messages
2011-12-01 08:10:21	ezio.melotti	create