Where Are The Project Files?

You can put related program components together, even if they are in different languages or file formats. Like this: conventional code structure:

• application/file1: feature1 documentation, feature2 documentation;
• application/file2: feature1 source code, feature2 source code;
• tests/file3: feature1 tests, feature2 tests.

Logical code structure:

• file1:
  • section1: feature1 documentation, feature1 source code, feature1 tests,
  • section2: feature2 documentation, feature2 source code, feature2 tests.

Your project's main programming language can be extended with a scripting language like Python or Emacs Lisp, which can be used to generate code. Great for boilerplate code.

Features of macros in Emacs Lisp inside an Org file that I haven't found in other literal project systems:

• access to the whole text of the tangled file (for whole project analysis),
• shared environment across macro invocations (for counters).

To file sections, to other files, URLs.

Export to HTML produces a very nicely formatted document. Also, GitHub shows .org files as a formatted HTML page, though macros and :noexport: sections are not supported.

The best text editor choice for Org files is Emacs. There are plugins for some other text editors with varying level of support.

Emacs may become less responsive with big and complex Org mode files. Projects with big feature scope will be difficult to understand as one file. But, maybe it's a good thing, and helps prevent feature creep?

Markers for code blocks: #+begin_src, #+end_src, etc litter the file. Besides your project's main programming language syntax and formatting, you now also have to spend time formatting Org.

Markdown has less intrusive syntax, however Org/Emacs Lisp tandem seem to be the most powerful for writing 1.2.

The compiler reports errors and warnings with line numbers of the source files that are extracted from the Org files, not line numbers in the Org file.

If you want to license your project properly and apply different licenses to project source files and documentation, it's a hassle to do that.