[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From   Nick Winter <[email protected]>
To   [email protected]
Subject   Re: st: re: TeX template for PDF help files
Date   Mon, 23 Nov 2009 09:30:57 -0500

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

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

*   For searches and help try:

Nicholas Winter                                 434.924.6994 t
Assistant Professor                             434.924.3359 f
Department of Politics                  [email protected] e
University of Virginia w
PO Box 400787, 100 Cabell Hall
Charlottesville, VA 22904

*   For searches and help try:

© Copyright 1996–2024 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index