3 ms·

I know it is not the primary use of Org mode, but does anyone uses org mode for documentation (instead of .md or .rst markdown files)?

goku12 3y ago
Org mode is actually a great lightweight markup format - much more standardized and rational than markdown. I maintain my knowledge base on it using org-roam. Org roam forms an easily searchable and navigable web of information. That includes everything from bookmarks and cheatsheets to daily journals. (I think obsidian does the same with markdown, but I haven't used it).
- deafpolygon 3y ago
  > much more standardized and rational than markdown Can you explain? I mean, I imagine there aren't really various flavors of Org Mode, but that doesn't make it standardized.
  - kramerger 3y ago
    See this https://www.reddit.com/r/AskProgramming/comments/aaol8t/why_does_markdown_not_have_a_standard/ https://www.reddit.com/r/AskProgramming/comments/aaol8t/why_...
    - deafpolygon 3y ago
      That refers to Markdown. I'm asking about how Org Mode is 'standardized'.
      - mediumsmart 3y ago
        It uses standard org mode plaintext.
      - kramerger 3y ago
        Org mode is standardised, markdown is not.
  - goku12 3y ago
    There are two reasons why I call Org mode standardized. > I imagine there aren't really various flavors of Org Mode, but that doesn't make it standardized. All the implementations that call themselves org-mode follow the conventions set by the canonical implementation - the Emacs org-mode. While this may not sound like a good reason to call it standardized, the practical implication is a vast difference from what you get with various markdown flavors. In the latter case, the only way to make sure that your markdown is correct is to test it with the target implementation. The second reason is that there is an actual effort to standardize org-mode - called Orgdown [1]. Org-mode is already more or less uniform across implementations. This effort tries to write it down as a reference. Markdown has a similar effort called CommonMark. But if you want to know why it's different, you have to look at the history of why it isn't called 'Standard Markdown'. [1] https://gitlab.com/publicvoit/orgdown https://gitlab.com/publicvoit/orgdown
yashrk 3y ago
I used org-mode files to save the examples of complex commands and code snippets (for example, for Docker, Kubernetes, bash, SQL and CQL). From the reader point of view it's literally documentation, although I'm not a professional technical writer and the only reader it's just myself (ok, sometimes I share some of this files with friends and family). If you use Emacs, you will have great editor with powerful preview features (images, formatting, table processor with formulae, code execution inside the text), and the pipeline for generating HTML or PDF will be approximately the same as with .md/.rst (org-mode is even supported by GitLab and GitHub web interface, although not perfectly). But the support of the org-mode outside Emacs is worse than of Markdown and reStructuredText.
zilti 3y ago
I use it for documentation, I created chicken scheme extensions as literate programming, having code, documentation, runnable examples, and tests all in the same source; then I use tangle and weave to generate the respective files.

goku12 3y ago

Org mode is actually a great lightweight markup format - much more standardized and rational than markdown. I maintain my knowledge base on it using org-roam. Org roam forms an easily searchable and navigable web of information. That includes everything from bookmarks and cheatsheets to daily journals. (I think obsidian does the same with markdown, but I haven't used it).

deafpolygon 3y ago
> much more standardized and rational than markdown Can you explain? I mean, I imagine there aren't really various flavors of Org Mode, but that doesn't make it standardized.
- kramerger 3y ago
  See this https://www.reddit.com/r/AskProgramming/comments/aaol8t/why_does_markdown_not_have_a_standard/ https://www.reddit.com/r/AskProgramming/comments/aaol8t/why_...
  - deafpolygon 3y ago
    That refers to Markdown. I'm asking about how Org Mode is 'standardized'.
    - mediumsmart 3y ago
      It uses standard org mode plaintext.
    - kramerger 3y ago
      Org mode is standardised, markdown is not.
- goku12 3y ago
  There are two reasons why I call Org mode standardized. > I imagine there aren't really various flavors of Org Mode, but that doesn't make it standardized. All the implementations that call themselves org-mode follow the conventions set by the canonical implementation - the Emacs org-mode. While this may not sound like a good reason to call it standardized, the practical implication is a vast difference from what you get with various markdown flavors. In the latter case, the only way to make sure that your markdown is correct is to test it with the target implementation. The second reason is that there is an actual effort to standardize org-mode - called Orgdown [1]. Org-mode is already more or less uniform across implementations. This effort tries to write it down as a reference. Markdown has a similar effort called CommonMark. But if you want to know why it's different, you have to look at the history of why it isn't called 'Standard Markdown'. [1] https://gitlab.com/publicvoit/orgdown https://gitlab.com/publicvoit/orgdown

yashrk 3y ago

I used org-mode files to save the examples of complex commands and code snippets (for example, for Docker, Kubernetes, bash, SQL and CQL). From the reader point of view it's literally documentation, although I'm not a professional technical writer and the only reader it's just myself (ok, sometimes I share some of this files with friends and family). If you use Emacs, you will have great editor with powerful preview features (images, formatting, table processor with formulae, code execution inside the text), and the pipeline for generating HTML or PDF will be approximately the same as with .md/.rst (org-mode is even supported by GitLab and GitHub web interface, although not perfectly). But the support of the org-mode outside Emacs is worse than of Markdown and reStructuredText.

zilti 3y ago

I use it for documentation, I created chicken scheme extensions as literate programming, having code, documentation, runnable examples, and tests all in the same source; then I use tangle and weave to generate the respective files.