3 ms·

Read the source with a question in mind. For example, how does some software create a particular kind of file? (I did this recently for Pandoc's EPUB writer-- w

by sj4nz 15y ago

Read the source with a question in mind. For example, how does some software create a particular kind of file? (I did this recently for Pandoc's EPUB writer-- while this software is in Haskell and not Python, the same rules apply.) Do lots of searches for keywords that seem appropriate to your question. When you find a class or function, trace its execution until you understand it. Learn the difference between function calls and function definitions--hopefully the formatting of the source makes a distinction. [For example, in JavaScript, Douglas Crockford recommends whitespace hints for functions, "function name () {}" would be a definition and "function name();" would be a call. The space between the name and the '(' is the clue for the difference. This is not part of the JavaScript language per-se.] Write down other questions or make notes about anything you don't understand. With most source, there's almost never any "best place" to start unless you have a question in mind. I don't think anyone can read source like a novel, because it is not a linear narrative--it is much more like a choose-your-own-adventure book. The longer you read and skim the source code of any system, you'll find that you know "where everything is" and just like a choose-your-own-adventure book, you'll slowly internalize when it tells you to turn to page 78 that the dragon is going to eat you without needing to turn and read that page.

nsomaru 15y ago
Thanks for your reply, I just hope I manage to escape the dragons and save the heroine ;) Do you use a simple pen-paper method for taking notes? How do you keep it all together?
- sj4nz 15y ago
  I do like paper, its very reliable with WiFi signals and very efficient with battery life. Pencils are nice because they provide undo. If I just need to find the answers for a one-off change or fix, I'll use plain white printer paper (dated and labeled at the top for future archival or disposal). I'll draw boxes/diagrams/mind-maps like crazy if I need them. If its a major system that I'll be working with a long time, I go with insanely cheap composition books of the same width and height (standardize!) Seriously, don't spend more than a dollar for a notebook that has a good chance you'll throw it away in a year. If you're going to use one for your own journaling/designing and not mere notetaking, go ahead and splurge--spend $2. Edit wrt Archival: Mostly, its being able to put the composition books away. Label and date the front of them so you can flip through them. I use different colors of covers so for any 4-5 of them I have "active" stand out and have fewer problems grabbing "the wrong book" when I know which color is which project. That's on the outside. On the inside, I reserve the first 5-6 pages for a handwritten table-of-contents that I update approximately monthly. All I do is dedicate one line per page in the book and summarize the contents of that page. This makes is easier to find relevant content inside without having to flip through 80 double-sided pages, I can skim 4-5 pages of topic lists. When things get too old or irrelevant, dating them helps you figure out if you need to throw the books away. (This is why you don't spend big money on these books, e.g. I would feel really guilty about throwing away a nice Moleskine book, but no qualms at all about tossing a $2 comp-book.)
  - nsomaru 15y ago
    Could you explain your archival system? If you're looking for something later do you have an index or something to find the right page? I'm also one of those people who is obsessed with speed and neatness (a terrible combination) and if my notes are not beautiful I am loathe to keep them. How can one manage this tradeoff?
    - sj4nz 15y ago
      (I added explanation of my indexing in previous comment.) Ditch cursive if you're still writing in it. Pick up a $4 copy of "The Italic Way to Beautiful Handwriting." Remind yourself that the purpose of the notes is to off-load the work of long-term memory from your brain until you have mastered your understanding of whatever you're working on. That's all. Beautiful things are things you publish and we don't publish books full of nothing but notes, no one else will bother reading them unless you die famous. E.g. http://www.englishcompanion.com/pdfDocs/davincinotes.pdf http://www.englishcompanion.com/pdfDocs/davincinotes.pdf Most of us will not die famous, so you shouldn't worry about your notes being beautiful. Davinci's notes aren't especially "polished," that isn't why he made them. Also, (from the pdf that reminded me), leave yourself some white space for future communications with yourself as seen in http://en.wikipedia.org/wiki/Cornell_Notes http://en.wikipedia.org/wiki/Cornell_Notes
      - Forrest7778 15y ago
        Organize your notes by page page number and paragraph - then you can label revisions on a separate page pointing to the revised page. Using sections/chapters helps with this as well.

by sj4nz 15y ago

nsomaru 15y ago

Thanks for your reply, I just hope I manage to escape the dragons and save the heroine ;) Do you use a simple pen-paper method for taking notes? How do you keep it all together?

sj4nz 15y ago
I do like paper, its very reliable with WiFi signals and very efficient with battery life. Pencils are nice because they provide undo. If I just need to find the answers for a one-off change or fix, I'll use plain white printer paper (dated and labeled at the top for future archival or disposal). I'll draw boxes/diagrams/mind-maps like crazy if I need them. If its a major system that I'll be working with a long time, I go with insanely cheap composition books of the same width and height (standardize!) Seriously, don't spend more than a dollar for a notebook that has a good chance you'll throw it away in a year. If you're going to use one for your own journaling/designing and not mere notetaking, go ahead and splurge--spend $2. Edit wrt Archival: Mostly, its being able to put the composition books away. Label and date the front of them so you can flip through them. I use different colors of covers so for any 4-5 of them I have "active" stand out and have fewer problems grabbing "the wrong book" when I know which color is which project. That's on the outside. On the inside, I reserve the first 5-6 pages for a handwritten table-of-contents that I update approximately monthly. All I do is dedicate one line per page in the book and summarize the contents of that page. This makes is easier to find relevant content inside without having to flip through 80 double-sided pages, I can skim 4-5 pages of topic lists. When things get too old or irrelevant, dating them helps you figure out if you need to throw the books away. (This is why you don't spend big money on these books, e.g. I would feel really guilty about throwing away a nice Moleskine book, but no qualms at all about tossing a $2 comp-book.)
- nsomaru 15y ago
  Could you explain your archival system? If you're looking for something later do you have an index or something to find the right page? I'm also one of those people who is obsessed with speed and neatness (a terrible combination) and if my notes are not beautiful I am loathe to keep them. How can one manage this tradeoff?
  - sj4nz 15y ago
    (I added explanation of my indexing in previous comment.) Ditch cursive if you're still writing in it. Pick up a $4 copy of "The Italic Way to Beautiful Handwriting." Remind yourself that the purpose of the notes is to off-load the work of long-term memory from your brain until you have mastered your understanding of whatever you're working on. That's all. Beautiful things are things you publish and we don't publish books full of nothing but notes, no one else will bother reading them unless you die famous. E.g. http://www.englishcompanion.com/pdfDocs/davincinotes.pdf http://www.englishcompanion.com/pdfDocs/davincinotes.pdf Most of us will not die famous, so you shouldn't worry about your notes being beautiful. Davinci's notes aren't especially "polished," that isn't why he made them. Also, (from the pdf that reminded me), leave yourself some white space for future communications with yourself as seen in http://en.wikipedia.org/wiki/Cornell_Notes http://en.wikipedia.org/wiki/Cornell_Notes
    - Forrest7778 15y ago
      Organize your notes by page page number and paragraph - then you can label revisions on a separate page pointing to the revised page. Using sections/chapters helps with this as well.