Technical Note 0
How to write a Lua Technical Note
There are no official guidelines for writing a Lua Technical Note.
You may read
On the Elements of a Technote,
Macintosh Technical Notes,
read these documents just for an idea of what technical notes look like;
Lua Technical Notes are much more informal.
Below is a personal (and self-referential!) view of how to write LTNs.
How to write an LTN
by Reuben Thomas
An LTN should have the following structure:
- The problem - Motivation and statement
- The solution - Description
- Explanation and justification
- Weaknesses and suggested improvements
Lua is a brilliantly economical tool for solving many programming problems.
Unfortunately, its economy and flexibility of design can confuse the
newcomer: they may find a clumsy solution to their problem, or worse, not
see one at all, when there is a simple and elegant solution waiting to be
found. Unlike users of most languages, who simply program in them, Lua
programmers will often want to embed, interface to, or even change Lua.
Various libraries and tools have grown up to meet many of these needs, such
as tolua, CGILua and LuaSocket. However, some needs are more abstract, and
cannot easily be met by a tool or library; questions such as: How can I
integrate Lua into my C++ program? How can I interface Lua to another
language? How can I avoid pausing my game for garbage collection? Questions
like these are best tackled by HOWTO-like documents, and this is what the
LTN series aims to do. But how should LTNs best be written in order to meet
An LTN should have the following properties:
It should address a real need. As a rule of thumb, if you can be motivated
to write an LTN, it's probably addressing a real need, though it's even
better if others have asked for solutions to the problem it addresses.
It should be brief. This allows others to read, understand and use the
knowledge it contains as quickly as possible; or, on the other hand, to
discard it if it's no good to them. As part of this, it should not be
necessary to read the whole LTN to know if it's what you need.
It should be authoritative. An inaccurate or badly thought out LTN may
well be worse than nothing. Again, if you feel like writing an LTN, you'll
probably know what you're talking about. The Lua designers act as editors
for the series, which also helps.
There are two parts to the solution: form and content. The content is up to
the author; the suggested form for an LTN is as follows:
- Summarise the LTN.
- The problem
- Motivate the problem: why is it important. End with a clear
statement. This will help both you and the reader to focus. By the end of
this section the reader should know if the LTN is useful for them.
- The solution
- Describe the solution, without elaborating on the whys and
wherefores more than necessary. By the end of this section, a reader who's
in a hurry should be able to implement the solution.
- Explain and justify why you designed your solution the way you
did. This will hopefully convince the skeptical and reassure the cautious
that your solution is good and you know what you're doing. Peripheral
matters and non-critical subtleties can be explored here (but keep it
- Discuss weaknesses of your solution, say why they're not
critical to its success, and suggest future improvements. This is where
you'll really convince the skeptic you know your stuff.
- Summarise, and give a wider perspective on the problem and solution.
This structure follows standard practice for good technical writing. The
simple five-part structure encourages brevity, fits most conceivable LTNs,
is simple for the author and reader to follow, and allows most readers to
get everything they need from the LTN by starting at the top and reading
until they've had enough.
One size never fits all. The proposed structure will be too detailed for
some, not enough for others, and simply irrelevant to others. I have said
nothing about how actually to write
"The Elements of Style"
by Strunk and White for clear, brief guidance on this).
Nonetheless, if most authors
follow this structure, they will hopefully find LTNs easier to write, and
readers will certainly find them easier to read because, if nothing else, of
their common structure.
Lua's brilliance lies largely in providing generally applicable mechanisms
rather than solutions to specific problems. Nevertheless, many problems crop
up frequently in the use of Lua. Some of the more concrete ones are
addressed by the variety of libraries and tools available; LTNs attempt to
address some of the more abstract kind. This LTN proposes a structure for
LTNs to make them more likely to be useful.
Finally, Lua programmers and LTN authors alike should always bear in mind
the first rule of Lua: "Do it in Lua". Lua almost always provides you with
the tools you need to solve your problem; it's just a case of seeing how to
use them. You should rarely have to use Lua API seriously, and even more
rarely have to change Lua itself. In terms of the three cardinal virtues,
Lua ranks laziness above impatience, and impatience above hubris. But of
course, hubris is just what it takes to write an LTN!
Thu Mar 18 14:03:37 BRT 2004