Skip to content

Instantly share code, notes, and snippets.

@jericson

jericson/documentation.md

Last active Dec 6, 2020
Embed
What would you like to do?
Text for introducing Stack Overflow Documentation

This is a book for learning more Perl. Neither a reference book nor a tutorial book, the Perl Cookbook serves as a companion book to both. It's for people who already know the basics but are wondering how to mix all those ingredients together into a complete program.—Tom Christiansen & Nathan Torkington, "Preface", Perl Cookbook

Asking on Stack Overflow is a bit like sitting at a sushi bar. If you respect the traditions, there is no better experience. Where else can you get a personalized answer to your programming question from a true master of the field? Unlike sushi, anyone with access to a search engine can sample Stack Overflow answers. What could be better?

Well, suppose someone is standing behind you at the bar and they grab some fish off your plate. After tasting it, they tell the chef, "Hey, could I get that with a bit more salt?" Or worse, "You prepared that all wrong!" Nobody would think to insult a sushi chef that way, but you sometimes see the moral equivelant on Stack Overflow questions. There's almost a ritualistic interplay between askers and answerers that makes the process insular at times. Do it right and it's a heavenly experience. Do it wrong, however . . .

Documentation is a bit like the cookbook section. Stack Overflow tags represent broad styles of programming. Each tag has a variety of topics representing "dishes" you might want to create. Finally, there are specific recipes, examples, for you to try out and adjust to you own needs. Since every programmer has different tools in the metaphorical kitchen and different tastes, there might be half-a-dozen examples for each topic. As working programmers up- and downvote examples, conventional styles rise to the top of the list. But expedient hacks (perhaps subsituting red food coloring for beats in red velvet cake) will be lower down on the list if needed.


This manual is intended for people who have never used TeX before, as well as for experienced TeX hackers. In other words, it's supposed to be a panacea that satisfies everybody, at the risk of satisfying nobody. Everything you need to know about TeX is explained here somewhere, and so are a lot of things that most users don't care about.

. . .

Another noteworthy characteristic of this manual is that it doesn't always tell the truth. When certain concepts of TeX are introduced informally, general rules will be stated; afterwards you will find that the rules aren't strictly true. In general, the later chapters contain more reliable information than the earlier ones do. The author feels that this technique of deliberate lying will actually make it easier for you to learn the ideas. Once you understand a simple but false rule, it will not be hard to supplement that rule with its exceptions.—Donald E. Knuth, TEXbook (1984)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.