summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--2020/info/14.md33
1 files changed, 8 insertions, 25 deletions
diff --git a/2020/info/14.md b/2020/info/14.md
index ffbb6d96..a55e1f47 100644
--- a/2020/info/14.md
+++ b/2020/info/14.md
@@ -1,28 +1,11 @@
# README-Driven Design
Adam Ard
-Org mode, among its numerous features, has the ability to do full
-literate programming (with tangling and weaving the way Donald Knuth
-originally intended). As a programmer, you can work comfortably,
-completely inside an org-mode buffer. When you are ready, emacs will
-generate the appropriate documentation and source code files for you.
-If you are a lone emacs user on your project, simply commit these
-exported files and keep your org file to yourself – no one is the
-wiser.
-
-Watch "README-Driven Design" to learn how you can
-annotate code snippets in an org file so they can be automatically
-exported to their proper locations in your source tree. Keep
-important information about your project where it should be: right
-next to the code itself. Not as ugly, out-of-date notes sitting
-behind comment characters in your source files, but front and center
-in well-formatted markdown and pdf files.
-
-And, for advanced use cases, see how you can even use a full-fledged
-macro processor like m4 to personalize your workflow even more.
-Literate programming on steroids!
-
-I'll walk you through the whole process, starting from an empty
-project README.org to a simple example that generates source and
-documentation.
-
+Many source code projects these days begin with a README file. While most
+people use markdown, if you use org-mode you can use literate programming
+to generate all of your source code directly from the documentation.
+
+This strategy is a great way to keep your documentation from getting
+outdated, and it allows you to use all the other wonderful features of
+org-mode. Watch "README Driven Design," to see exactly how to make your
+README file a powerful literate document.