5 ms·

I use Markdown documents in Git repositories whenever I can. Also try to evangelize for this at work. PRs then include relevant changes to both code and docs an

I use Markdown documents in Git repositories whenever I can. Also try to evangelize for this at work. PRs then include relevant changes to both code and docs and it's beautiful. For personal project docs I use this exclusively. At work it depends on the team, some people don't like it, but most often it is because they don't like keeping docs at all, not because of an alternative preference. I avoid UI and WYSIWYG based systems like Confluence like plague. I personally can't stand them and every time I have to use one I do my hardest to pretend I'm writing Markdown in my head. For personal agenda I use Apple Notes with basically just a huge list of things to do and events that are about to happen and I curate that list more or less non stop during the day. If something comes up and I'm with people and don't want to be rude and spend too much time on the phone editing things to be in the right order and have all the relevant info captured with them, I just plop a line at the top of the note knowing I'll groom it later.

bluenose69 7y ago
This is pretty much exactly what I do, too. The only difference is that my use of Apple Notes is mostly for quick, personal things ... I move material into Markdown documents within git repositories as soon as I can, because then it's easy to share it, trace changes, and organize contributions. Oh, and one more thing: my Markdown documents are normally R-Markdown documents, so I can incorporate calculations and graphs as needed. (Also, R-Markdown has a nice metadata section for document title, author, date, etc.)
- johnminter 7y ago
  I, too, am a fan of R-markdown for this purpose
tonyoaky 7y ago
Do you use any specific structure for your markdown documents? Confluence i believe helps structure the knowledge
- thundergolfer 7y ago
  But Confluence crucially isn’t source-controlled within the same repo. It’s not source controlled at all. I find this a terrible workflow problem. As often a change to code requires a small or large change to documentation that is best bundled in alongside.
  - tmaly 7y ago
    It does have change history of each page. However, if you use a lot of embedded tables, it is quite hard to do change comparisons.
vendiddy 7y ago
I do this too. I use Sublime text in distraction free mode with a git plugin so I can easily commit/push changes. On my Mac, I can do the 4-finger swipe to check my full-screen notes. Usually I have a folder structure like notes/2019-10/2019-10-21.txt. If I want to tag things, I'll just write #idea #work somewhere in the text file. Then easy to search with Sublime or whatever tool you want. I also like this approach because it's future-proof. Just a folder full of text files. Curious how others are handling this same workflow.
- deleted 7y ago
  [deleted]
- synlatexc 7y ago
  Same here, though mine is one gigantic text file that dates back ~20 years. Expect to continue updating/referencing it for decades to come, bar some calamity.
  - doomjunky 7y ago
    How? Chronologically or structured by topics? Appending at the top or buttom? Timestamps? Tags? How do you navigate through the file?
    - synlatexc 7y ago
      There are a couple sections, but for the most part it's chronological, with new entries at the bottom. Started adding dates to new notes/quotes/observations about 5 years ago. It's a sprawling mess, so I rely on search to find what I'm after. I reference it often -- it's like an extension of my brain.
      - 64738 7y ago
        I do the exact same thing. Just a text file that these days I store in a Dropbox folder so that no matter what system I'm on I can just "vi ~/Dropbox/notes.txt". Similarly, several years ago I added a keybind to my .vimrc that, by typing ",a" I'm moved to the bottom of the file and today's date with a separator line underneath. My leader key is "," and I mnemonically associate "a" with "append". The earliest date recorded in it goes back to 2006 and is about 300KB in size. I still reference and add to it on a regular basis.

bluenose69 7y ago

This is pretty much exactly what I do, too. The only difference is that my use of Apple Notes is mostly for quick, personal things ... I move material into Markdown documents within git repositories as soon as I can, because then it's easy to share it, trace changes, and organize contributions. Oh, and one more thing: my Markdown documents are normally R-Markdown documents, so I can incorporate calculations and graphs as needed. (Also, R-Markdown has a nice metadata section for document title, author, date, etc.)

johnminter 7y ago
I, too, am a fan of R-markdown for this purpose

tonyoaky 7y ago

Do you use any specific structure for your markdown documents? Confluence i believe helps structure the knowledge

thundergolfer 7y ago
But Confluence crucially isn’t source-controlled within the same repo. It’s not source controlled at all. I find this a terrible workflow problem. As often a change to code requires a small or large change to documentation that is best bundled in alongside.
- tmaly 7y ago
  It does have change history of each page. However, if you use a lot of embedded tables, it is quite hard to do change comparisons.

vendiddy 7y ago

I do this too. I use Sublime text in distraction free mode with a git plugin so I can easily commit/push changes. On my Mac, I can do the 4-finger swipe to check my full-screen notes. Usually I have a folder structure like notes/2019-10/2019-10-21.txt. If I want to tag things, I'll just write #idea #work somewhere in the text file. Then easy to search with Sublime or whatever tool you want. I also like this approach because it's future-proof. Just a folder full of text files. Curious how others are handling this same workflow.

deleted 7y ago
[deleted]
synlatexc 7y ago
Same here, though mine is one gigantic text file that dates back ~20 years. Expect to continue updating/referencing it for decades to come, bar some calamity.
- doomjunky 7y ago
  How? Chronologically or structured by topics? Appending at the top or buttom? Timestamps? Tags? How do you navigate through the file?
  - synlatexc 7y ago
    There are a couple sections, but for the most part it's chronological, with new entries at the bottom. Started adding dates to new notes/quotes/observations about 5 years ago. It's a sprawling mess, so I rely on search to find what I'm after. I reference it often -- it's like an extension of my brain.
    - 64738 7y ago
      I do the exact same thing. Just a text file that these days I store in a Dropbox folder so that no matter what system I'm on I can just "vi ~/Dropbox/notes.txt". Similarly, several years ago I added a keybind to my .vimrc that, by typing ",a" I'm moved to the bottom of the file and today's date with a separator line underneath. My leader key is "," and I mnemonically associate "a" with "append". The earliest date recorded in it goes back to 2006 and is about 300KB in size. I still reference and add to it on a regular basis.