From b08fc8cd8dcaab2b6fd2c346e5801984a1f33b2c Mon Sep 17 00:00:00 2001 From: Sacha Chua Date: Tue, 10 Nov 2020 22:48:29 -0500 Subject: Update README-Driven Design summary --- 2020/info/14.md | 33 ++++++++------------------------- 1 file changed, 8 insertions(+), 25 deletions(-) (limited to '2020') 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. -- cgit v1.2.3