Re: st: re: TeX template for PDF help files

[Nick Winter <nwinter@virginia.edu>]

Just my two cents (worth about half a cent in these economic times, I 
guess):

It seems to me an extremely nice feature of Stata's user-extensibility, 
and the SSC integration that makes that extensibility relatively easy 
and seamless for even inexperienced users, is that user-written programs 
look and act like official Stata programs, including their help files.

I think it is easy for those of us comfortable with programming, 
multiple file formats and markup languages, the installation of helper 
applications, etc., it is easy to forget how quickly many users will 
become uncomfortable with things that don't look and act like official 
Stata.

So in my humble opinion, a move toward replacing SMCL help files with 
PDFs would be a mistake, unless that is part of a move by StataCorp to 
revamp the help system.  But otherwise, we'll just end up with a mess 
where each author has their own templates, "look," etc.


Re: SMCL, I'm no huge fan, but it does seem to have some good features 
tied to the needs of displaying things in Stata (e.g., ability to run 
example code).  In any case, I find coding SMCL by hand about as hard as 
coding simple HTML by hand, and considerably easier than coding simple 
LaTeX by hand.  So I'd love to see the next iteration of the do-file 
editor include a more full-blown environment for writing help files.

- Nick Winter


Maarten buis wrote:
> --- On Mon, 23/11/09, Roy Wada wrote:
> > I thought about the translator thing, and this should not
> > be difficult. I also see that the Stata Corp is silent on 
> > this issue. 
>
> Probably because the entire discussion took place over the
> weekend.
>
> > If you look at the official help files they avoid writing
> > too much and use small paragraphs only. Users don't know
> > this, and they cram too much, and it starts looking hideous
> > This is how people get sucked into putting hours and hours
> > of work with nothing to show for it. 
>
> My analysis would be different: StataCorp has always had the
> paper manual, so the help files were just there as a quick
> reference, hence the short paragraphs containing only basic 
> information (there are exceptsions, see for example 
> -help classman- or -help dialog_programming-). 
>
> We could also mantain two sets of documentation, but it is
> easier to maintain 1 document rather than 2. I have played 
> around with that two level documentation format, but I found 
> it too much work and too easy to get inconsitencies across 
> documentations. So, I will stick with using smcl help files.
>
> -- Maarten
>
> --------------------------
> Maarten L. Buis
> Institut fuer Soziologie
> Universitaet Tuebingen
> Wilhelmstrasse 36
> 72074 Tuebingen
> Germany
>
> http://www.maartenbuis.nl
> --------------------------
>
>
>       
>
> *
> *   For searches and help try:
> *   http://www.stata.com/help.cgi?search
> *   http://www.stata.com/support/statalist/faq
> *   http://www.ats.ucla.edu/stat/stata/

--
--------------------------------------------------------------
Nicholas Winter                                 434.924.6994 t
Assistant Professor                             434.924.3359 f
Department of Politics                  nwinter@virginia.edu e
University of Virginia          faculty.virginia.edu/nwinter w
PO Box 400787, 100 Cabell Hall
Charlottesville, VA 22904

*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/