Re: st: A gentler introduction to Statalist and Seven Deadly Sins

[n j cox <n.j.cox@durham.ac.uk>]

The first FAQ for Statalist was put together about a decade or
more ago by David Wormuth. The present document owes most to
Marcello Pagano, Bill Gould, Kit Baum and myself, although many
others have made useful suggestions. Much of one section owes its
origin to various questions posed by Jan De Leeuw. The presentation
owes most to several StataCorp people including Ken Higbee, Louisa
Gilmore and Annette Fett. I am the present maintainer but I want
to emphasise the contributions of these several others.

Looking at the present FAQ again I find it a little hard to
believe that Roy is talking about the same document. It's a click
away, but here is the structure once more.

0.  Introduction
0.1  What is Statalist for?
0.2  How does a list work?
0.3  How does Statalist work?
0.4  Who is responsible for Statalist?

1.  Before you post

2.  How to use Statalist: mechanics
2.1  I want to join Statalist. What do I do?
2.2  How do I send questions to Statalist?
2.3  I want to stop getting Statalist messages. What do I do?
2.4  I stopped getting Statalist messages. What happened?
2.5  I want FEWER Statalist messages. What do I do?
2.6  I want MORE frequent Statalist messages. What do I do?
2.7  An easy way to handle 2.1 and 2.3 - 2.6
2.8  I missed some messages. Or, I want to look at past messages.
2.9  When you go on vacation
2.10  How do I contact the list maintainer?

3.  How to use Statalist: advice

4.  What to do if you do not get an answer

5.  FAQs on Stata
5.1  Where to find this FAQ
5.2  Where to find other FAQs on Stata
5.3  Updates to Stata
5.4  Ways to learn how to use Stata

6.  Ado-files FAQ
6.1  Where to find Stata-released ado (STB/SJ) files
6.2  User-contributed ado-files: the SSC Archive
6.3  Are there other sources of user-written ado-files?
6.4  What is the relationship between ado-files from the SSC Archive, 
other user-written ados, ados published in the Stata Journal, and ados 
that are part of official Stata?
6.5  Does downloading an upgraded or augmented STB/SJ contribution 
automatically replace an earlier one, and does it inherit all 
functionality of the previous version?
6.6  What happens if an STB/SJ contribution upgrades, corrects or 
expands an official ado-file or built-in command?
6.7  How do I know if official ado upgrades (and executable upgrades) 
incorporate the functionality of previous STB/SJ contributions (so that 
the STB/SJ contributions become "obsolete")?

7.  Miscellaneous
7.1  What is the correct way to pronounce 'Stata'?
7.2  What is the correct way to write 'Stata'?

Reading the whole thing at once should take at most a few minutes.
I am sure that most people would skim and skip and extract what
was important to them by using the many headings as guides.
Roy seems almost proud tbat he hadn't read it all until recently,
but that was his choice. What's more important is that someone
relatively new to the list can see headings like

1.  Before you post
2.  How to use Statalist: mechanics
3.  How to use Statalist: advice

If these headings are not plain enough, please do let me know.

To state that stuff is "buried", as Roy does twice, is to imply
that Statalist members are incapable of reading a document that
is child's play compared with the more technical material that
they will read daily. There is nothing hidden, or in small
print, or the equivalent of legal footnotes. The FAQ itself is
just one document. There are links to other stuff that might be
interesting or useful, but the FAQ is one integral document.

That said, there is some tension between two roles of the FAQ:
1. As a reference document.
2. As an introduction to Statalist.
From time to time, this tension has exercised various people, and
various alternatives have been tried.

We used to send a longer introduction together with the
welcome message that people get when they join. We got
a strong impression that all too often this was deleted
on receipt, or quickly lost sight of, and it needed
updating surprisingly often, and changing that was an
imposition on support staff at Harvard School of Public Health
who work with Marcello Pagano. Also, that made two
documents to maintain.

We have also played with an idea of an executive summary
and have in fact posted such from time to time (e.g.
<http://www.stata.com/statalist/archive/2003-07/msg00412.html>).

I have never been convinced that this was quite the
right solution, nor did I ever get any positive comments
about such summaries, or sense that in any way they improved
matters. It's rather difficult to condense
what is already a fairly terse document to essentials
without avoiding weak banalities ("Explain clearly what
your problem is") or, most crucially, ending up with lots
of negatives that would undoubtedly, and correctly, be
open to criticism as setting an unwelcome tone.

Roy's examples of the Seven Deadly Sins and the Ten
Commandments (8/10 negative) are not reassuring precedents
in that sense.

Segregating some of the advice might even make it more likely
that some people would find an excuse not to read anything
else. Terse precepts are sometimes useful when they
encapsulate what you already know, but I think most
people learn from specific examples, not exhortations.

In any case I doubt that adding yet another section
to what is stated to be too long is the right way to go.

Roy's posting is timely as I have on one computer an
advanced draft of the FAQ that incorporates references
to Stata 10 (and manages to be a little shorter).
Naturally I will take note of any clear consensus that
emerges.

Nick
n.j.cox@durham.ac.uk

roy wada

There have been many repeat postings chastising alleged violators
of some standards for Statalist and asking them to read FAQ prior
to posting to Statalist. I have to say I haven't completely read FAQ,
either.

The author of FAQ took pains writing it, and we are better off
for having it. Having said that, it is too long to be paid attention to.

A frequently cited passage about the need for complete citation,
"Please do not assume that the literature familiar to you is familiar to
all..." is buried somewhere in FAQ. I knew I would find it there,
but I don't think I have ever seen it before.

The most pertinent advice about the standards and protocols for
posting to Statalist are buried in the middle of FAQ, where it will
not be found by the newest members of Statalist.

Yes, it would be nice if everyone actually read FAQ, but it would be
an entrapment to think that they actually would. Think footnotes in
a legal document. Some people are getting caught by them.

If there are such things as Seven Deadly Sins that should be avoided
when posting to Statalist, then perhaps they could be made available
at the top of FAQ. They might be specified in the confirmation email
from the majordomo upon subscribing to Statalist.

By making a short list available, think of it as moving away from
Hammurabi's
Code, which was publicized in its time but too complicated to be easily
understood, to something more manageable like Ten Commandments.

Ten is good. Seven is better. 282 is too many. A checklist should be short.

Any potential list of seven deadly sins PROBABLY should include something
about incomplete literature citation. I would also include something about
incomplete descritions of a Stata command, but that would be my personal
perference.
*
*   For searches and help try:
*   http://www.stata.com/support/faqs/res/findit.html
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/