# 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):

Title:    Kifu Assembly Notes
Subtitle: Week 38 (Week 45 of Project)
Author: Hilton Lipschitz
Affiliation: Noverse LLC
Web:    https://noverse.com
Date:   March 2, 2012

# Optimization

Now that we have a large dataset, need to speed things up. Running performance stats to find the bottlenecks.

BRANCH: optimize-1

- Add TEST to project so I can run benchmarks and profile tests

Here goes

rails generate performance_test aging_by_event_summary

And added the DevelopmentProfiler class

Use as

DevelopmentProfiler::prof("<profile_file_name>") do
# CODE TO PROFILE
end

## Improvements

Start @36.02

- aging_by_event_summary/0.4s: Fewer billings calls and assed this_bill_ variants
- aging_by_account_detail/2.0s: No include phones and emails in query (this will slow down the collections report)
- import
- No validations after saving an allocation /2.0s
- No validations on creating an attending/1.0s
- No validations on others/0.8s
- Move some observers into classes/0.06s @27.31
- Move more into classes/0.16s @27.15
- Move more into classes/-.--s @26.44
- Move all into classes/-.--s @26.20

## TODO

- ✓ Use this_bill_ variant when getting Billing outstanding, payable or allocated
- ☐ aging_by_account_detail PDF is 62 seconds after changes (all in the PRAWN module!)

## More

- Fix billing messages
- BUG in parse_date on Event -> all observers need a self tag

- Cleaned up models, removed old observers
- Starting on Controllers

MERGE: develop

## Rename things

BRANCH: rename-1

- ✓ Rename review account and make it more RESTful
- ✓ Rename roll event
- ☐ Rename billings

IN VIEWS:

- ✓ Disable editing on closed events
- ☐ Sort events and some sub-tables in review

• 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:

## Step 3 - Postgres

As per http://yum.postgresql.org/howtoyum.php, edit the repo to exclude their postgres builds.

cd /etc/yum.repos.d

And edit the file appending exclude=postgresql* to _[base]_ and _[updates]_

scp -p pgdg-centos91-9.1-4.noarch.rpm root@client.com:/root/

On server

rpm -i pgdg-centos91-9.1-4.noarch.rpm

yum install postgresql-libs
yum install postgresql postgresql-server

service postgresql-9.1 initdb

NOTE: No need to add IP access as its local only. This will change when we move it to another server.

service postgresql-9.1 start
chkconfig --level 345 postgresql-9.1 on

su - postgres
createuser noverse
createdb -O noverse reportingdb_production

In /var/lib/pgsql/9.1/data/pg_hba.conf replace _ident_ with _trust_.

Test after restart to make _trust_ work (as root)

service postgresql-9.1 stop
service postgresql-9.1 start
psql -d reportingdb_production -U noverse

Database is UP!

## Step 4 - Web

### Ruby 1.9.3

On server, as root

yum install openssl-devel zlib-devel gcc gcc-c++ make autoconf readline-devel curl-devel expat-devel gettext-devel

On local

scp -p ruby-1.9.3-p194.tar root@client.com:/root/

On server

Install libyaml as per [http://collectiveidea.com/blog/archives/2011/10/31/install-ruby-193-with-libyaml-on-centos/]()

tar -C /tmp -xzvf yaml-0.1.4.tar.gz
cd /tmp/yaml-0.1.4
./configure --prefix=/usr
make
make install

Make ruby

cd
tar -C /tmp -xvf ruby-1.9.3-p194.tar
cd /tmp/ruby-1.9.3-p194/
make -j4
make install

Test

ruby --version
gem --version

OK

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:

Title:          %filltext:name=Project:default=Kifu% Assembly Notes
Subtitle:       Week %filltext:default=2:width=10% of Project
Project:        %filltext:name=Project:default=Kifu%
Author:         Hilton Lipschitz
Affiliation:    Noverse LLC
Web:            https://noverse.com
Date:           %B %e, %Y

Which gives:

I also use a TextExpander snippet to break it up into days ;mmd:

---

**%A %B %e, %Y**

Which gives me:

---

**Thursday January 3, 2013**

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.