summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSacha Chua <sacha@sachachua.com>2020-11-10 22:48:29 -0500
committerSacha Chua <sacha@sachachua.com>2020-11-10 22:48:29 -0500
commitb08fc8cd8dcaab2b6fd2c346e5801984a1f33b2c (patch)
treebfb93172c1bcb4bd7ebd59afd5abf8e380428cb8
parentc9242e20ccc9f39774dd6272c53a927b5311520a (diff)
downloademacsconf-wiki-b08fc8cd8dcaab2b6fd2c346e5801984a1f33b2c.tar.xz
emacsconf-wiki-b08fc8cd8dcaab2b6fd2c346e5801984a1f33b2c.zip
Update README-Driven Design summary
-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 &#x2013; 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.