Assembly Notes
Assembly Notes are documentation that a programmer creates to record all the steps they go through when crafting an application, setting up a new server or configuring a new device. The idea is to log all the things they do and all the commands they type in so that they can reproduce the process again later. Assembly Notes are personal or project internal, not shared.
I started writing these when I launched Noverse, and use them on all projects. I have notes for each step I performed when creating each application, more notes for how all servers are set up and configured and even notes on how the development environments are set up. In my case, I break these up into weekly files by project, store them in my standard project folder’s Notes folder and use these logs as the source when reporting progress to clients as well.
By noting everything, you miss nothing. And you have a script to reproduce what you did.
Assembly notes are different to to-do’s (although they often contain to-do notes). It is a record of what was tried, what was done, what worked, what did not, and how it all can be reproduced.
Project Assembly Notes
Here is a sample of the top of one of my Assembly Notes for Kifu (scroll down as it’s quite long):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
|
About these notes:
- They are written as Markdown files (using MultiMarkdown extensions).
- I have BBEdit running all the time with the current project and week’s Assembly Notes file open.
- I use Markdown Metadata headers to record the project, week and date of the notes (always a Friday).
- I often copy and paste command lines in to record what was used. And sometimes the data and output too.
- I usually log the branch name in case I need to go back.
- I use TextExpander shortcuts to create the unchecked ☐ and checked ✓ marks against to-do notes. I often create a plan, note it, then check each item off as I go. These are tactical plans, what I want to achieve in the next few hours.
- I write release notes in here too, then copy and paste them out into the application and release emails.
Server Build Notes
Here is an except from another project’s Server Build Notes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
|
On build notes:
- I include all dependencies and their installation commands.
- I include all version numbers so I can ‘clone’ the server easily and get the same environment back.
- I explain all decisions, even ones that will change later.
- I include tests to ensure the component works.
Benefits
One gets a lot of benefit from these including:
- The ability to build a new server quickly as you have a working script to follow.
- The ability to report clearly to clients all the work done in a period.
- The ability to go back and see why certain decisions were made.
- The ability to go back and see how things were done, so you can do them again better.
- Documentation on how things were done in other projects so you spend less time doing them in this project.
Tips and Tricks
I use a lot of snippets to make these. The Assembly Note header is a TextExpander snippet ;mma
that uses fill-ins and a form as follows:
1 2 3 4 5 6 7 |
|
Which gives:
I also use a TextExpander snippet to break it up into days ;mmd
:
1 2 3 |
|
Which gives me:
1 2 3 |
|
Finally, I track who reported what using a set of key marks (also TextExpander snippets), and use them in release notes:
- β/HL -
;bm
: Bug Mark (Bug reported by HL) - ⨍/HL -
;fm
: Feature Mark - ‽/HL -
;im
: Inquiry Mark (when doing research to answer an inquiry) - ∁/HL -
;om
: Other Mark (when doing other work for the client or their users)
It Just Takes Discipline
Creating Assembly Notes and keeping them up to date requires discipline and habit. I habitually open BBEdit and the current project’s Assembly Notes file when I start on a task, just as I habitually kick off the Billings Pro timer. And I am disciplined enough to use the open notes file to record what I want to get done, paste any notes and thoughts and check them off as I work. It did take a while to get used to working this way, but the benefits of having these process scripts lying around are just too great.
Try creating Assembly Notes from now on, one file a week, and ensure you ALT-TAB to this file when you are between tasks, or thinking or planning or running commands and write what you do. Before you know it, it will become habit and you will have an excellent log to work with.
Follow the author as @hiltmon on Twitter or @hiltmon on App.Net.