Documentation Formats

Life is full of things to catalog, especially for someone like me. Someone who loves organization in data and looking for patterns. Someone who is convinced that the random things in my life will probably come together someday like the unification theory. But how? How does one sort, contain, and search data?

The first step is recording the data. There are many ways to do this. Databases have traditionally been a great way. NoSQL databases with their loose document format are interesting. The second brain methodology uses documents or notes to contain the same thing. And while these documents can be formatted in things like Markdown and have front matter for categorization, much of the data is contained in the raw text which means a human has to parse and read it.

Before you expect this post to come to some epic realization, tl;dr; I still don’t have one. This post is about the methods out there I’m considering for sorting my life.

Option 1: SQL

I’m not a fan of no SQL databases. From my point of view, if you are going to create data to exist in a place that is typed, loose document formats make comparing and reading things hard. So structured data is better, hence SQL.

Pros:

  • The data is structured from the start
  • There are many different options for which SQL platform to use and many of them are interchangeable so there are options.
  • Things like normalization define best practices for working with something like this, so you don’t have to develop them yourself.

Cons:

  • You need to run a server somewhere.
  • It is not easily human decodable.
  • You need to learn to use SQL to really be successful and joins are fun (and hard).
  • Because structure is required you have to define it up front.

Option 2: Markdown

This is honestly what I’m currently using in my second brain with Obsidian. This may be the best of all worlds. It has the notion of storing structured data in front matter, and throughout the document with special tags. Much of the document remains readable in sentences, but it is in loose format and you have to create and maintain your own formatting standards.

Pros:

  • Format is loose so you don’t need to stress about it.
  • Much of the notes are human-readable.
  • There are many tools to convert markdown to the web for sharing.
  • Cost of starting is very low.

Cons:

  • Because the format is loose, the responsibility lies on the creator to maintain the structure desired.
  • The organization of individual documents is also important.
  • Search is only as good as you are at searching and remembering.
  • It’s easy to end up with a mess of documents.

Option 3: Stricter document format

This category contains things similar to markdown but with more structure. This category fits things like JSON, YAML, and TOML. This is following the Pragramtic Programmer guideline of storing things in the text but putting some structure behind it. Some of these formats are more readable than others.

Pros:

  • Easily computer parsable.
  • More human-readable than a SQL database

Cons:

  • No official typing.
  • Need to use a validator to confirm you have a valid document.
  • Nothing requires the structure like a SQL Table so searching could be difficult.

Summation

I don’t have a conclusion. I’m still thinking, but these are interesting options of how to start really putting the data together. Our lives are full of data, it’s a shame when it gets lost or mislabeled or put in a place where we can’t find it. Hopefully, I’ll start putting together something more useful.

WordPress and the Future

This site is currently hosted on a WordPress backend. I’ve been using wordpress for hosting many of my sites since around 2005. I’ve used several different providers and hosted a bunch of sites that are around and some that have gone away. WordPress has been a consistent tool across that process.

The problem: WordPress is heavy handed. It has morphed from a blogging platform to a full Content Management System (CMS). It has pluggins and extensions for pretty much everything. You can do so much with a wordpress site, but there in lies the problem. WordPress does everything, which means it is complicateed. Modifying and extending wordpress takes a bit of knowledge and as the system grows so does knowledge required to modify and work with it.

This site is hosted on a custom template version that I have modified without really understanding how all of it works. I get bits and pieces. I have added my own fonts and put in some of my own styles here and there. When it comes to big customizations there are pieces of this site that I don’t like. One of them is the person icon at the top of the page. When you hover over it, shows a white background and messes with page. I’m honestly afraid to spend the time to figure out how to fix it.

The technology behind wordpress is also getting a bit dated. It still works, but wordpress is built on PHP. PHP was great back in the day. In college I was part of a team that built an entire database project in PHP. But the technology is old and there are some newer technologies that are a little more fun to learn. So instead of investing in learning an older technology. I’m looking at some newer.

I would not be surprised if this site moves in the next year. I’m currently playing with Hugo, and I’ve looked at 11ty, and of course the standard Jekyll. The truth is that all of these are pretty similar. It just about which one you want to invest the time in learning and building. Hugo is written in Go. 11ty is Javascript, and Jekyll is Ruby.

Why choose Hugo? Why Move. I want more control. I don’t want my system to have the control. I want to be in the driver seat. The reason behind Hugo is a little bit silly. I want to learn to Go. There is this technology called Bubble Tea which is like NCurses on steriods for the Go programming language and I’d like to do some stuff there.

So here is learning go. Learning Hugo. Making better, more customizable sites, and getting my thoguhts out there with a technology that I enjoy.

Thinking About Themes

I’m not a visual designer, but I do like pretty things.

On the top of my mind recently has been the idea of my Purple Owl Theme. It comes from the “Night Owl” theme on MonoLisa’s website.

Blue background with a big purple highlight. Light gray as a text color. I love the theme, and I’ve tried to make a version of it for Obsidian. In doing so, I realized that actually figuring out what colors goes where is confusing. Colors that make sense on the MonoLisa site don’t make sense in my Obsidian theme. There are also a bunch of additional color and syntax settings for something like my Obsidian notes that aren’t really matched to any of the theme values from the MonoLisa site.

I look at some other themes like Monokia Pro and see that they are using mostly 6 colors and backgrounds.

There has to be a better solution to theming. Having to write themes for everything, customizing for each individual application. As we do themes at Airkit, the same thing applies. We have things like “Brand-Primary” and “Brand-Tint1” and various other colors defined within our apps.

After talking to a VERY smart coworker he turned me on to Design Tokens. Design tokens are the elements of style that Salesforce uses in their Lightning Design System (LDS). They define a set of tokens that are then used throughout their various different products. They use tools to take these defined tokens and send them out to SASS out for web products and p-lists for iOS, etc.

After looking at LDS Design Tokens, there are a bunch of things on there that aren’t exactly what I’m looking for. I’m looking for a way to define a few select attributes and have a tool interpret it into a full theme that is usable in many different applications. Looking at Solarized they only have 16 defined colors.

Anyway, I’m not done with anything yet. I’m just starting to think through this project.

Zacharyc Consulting

Last week I started two new companies. One of them is pretty straightforward and so I’m announcing it here today. I started zacharyc consulting which is a technology consulting business. There are many times I’ll be in a conversation with someone about technology and they are looking for guidance. With years in the field of tech I have a diverse background in the field. My goal in this business is to help advise businesses with their technology decisions. From making a website to social media, there are many technical questions that I can help answer.

This is not a replacement for my day job, and I’m probably not going to take on any project that is too significantly large. The goal is to provide guidance to those who need it and help people avoid investing in the wrong solution.

12 Tips for People New To Software Engineering

I’ve been working in the field of software for over 16 years now. I’ve worked for small companies, and I’ve worked for large companies. I have recommendations of books to read (though I really should start a database of books). I gave a small talk a couple of days ago, and I shared some points to start with. Here are the points that I advocated:

  • Learn Version Control Software – This was something that was mentioned in college, but not really harped on. In the real software world, everything is done with version control. It allows you to track changes and see how the software is made. Learn it! Git is the most common, but there are plenty of alternatives.
  • Read Books Often – It actually doesn’t have to be books, it can be blogs and various other things. Find stuff to read and stay up to date as best you can. Software is continually evolving. As people are writing software, they are evolving the practice of software engineering. New stuff will make your life better and easier.
  • Understand Computer Architecture – At some point in your career, understanding how a computer works will help you. I have a story about a buffer overflow in Swift that wasn’t pushed back to ObjC that took me days to debug, and I was only able to solve by realizing the one device we were working on was a 32 bit device. Understanding architecture will help you with understanding performance trade-offs.
  • Everything boils down to text – Everything is text, somehow. Packets going over the internet are really just text in disguise. Websites are mde in text. Everything is text. Even images are really bytes, which is text for computers. If you spend enough time, you can understand pretty much anything. It’s all a matter of time, usually not a technical limitation of understanding a problem.
  • Have a website – This is advice from Being Geek from Michael Lopp. Create a website. It’s not super hard to do and will look good on your resume. It’s a great way to show potential employers what you have done.
  • Do side projects – They don’t need to production level projects, but doing side projects is a great way to play with technology and learn about various different things. Notice a trend here, keep learning if you want to be successful.
  • Learn as many langauges as possible – You don’t need to be an expert in all of them, but understanding the basics in many different langauges will help you. Being able to understand the advantages of one language over another is super helpful. Picking up a second langague can be hard, but if you have many languages under your belt, picking up a new one isn’t super hard.
  • Learn people skills and start networking – Even though writing software is a skill, most projects are too complicated for any one person to do. You will need to work with others. Learning to do this effectively will help your career. It might also allow you to find different opportunites that might peak your interest.
  • Learn the command line – I don’t care what system you are on, there is a command line under it. Learning the command line will help you be efficient and work on many different environments. Remember, everything is text.
  • Keep notes and records – You will forget what you wrote in less than 3 months. Notes and records will be your best resource for remembering what you are thinking. Plus you remember more of what you write down. So write things down in a way you will be able to look back on them in the future.
  • Become a power user of your software – You will spend your days using development software. Learn the keyboard shortcuts and all the tricks you can to be more effective in your software. It will help you save time, and that time will add up. It will allow you to spend more time thinking about the “what” of software.
  • Learn about testing – saving one of the best for last. Testing can be your best friend. It can help you from breaking something you already had working and ensuring your objects behave the way you expect them to. I’ve worked for companies that have done too much testing (way too much UI testing can slow down development), but if you have a question, you probably don’t have enough.

Starting a Career in Software

laptop with code

I’ve written some blog posts on getting into the business of software development before. Specifically this list of books on programming, yet I had a conversation with a young engineer the other week and it made me wonder what else I could do to people get into the field. Luckily for me, this young engineer has friends who are also in college and also looking to get some information on the field.

Now, I’m famous for saying, “I’m a Zack of all trades, master of some (really few).” The truth is, when it comes to software, I’m not a super-strong master of many. I get the conceptual idea of a bunch of it, and I’m really just an expert at seeing a problem and understanding the solution. What I’m good at is finding resources to help me and understanding what the resources tell me and translating that into solutions.

Still, when I was starting, I wish there were a bunch of things people had told me. I wish I had known that literally, anything is possible in the world of computer programming if you are willing to dig deep enough to figure out what is going on. I wish I had been told some good places to start learning. I wish I had been told that it’s okay to ask any question once, but it’s really bad to ask the same question over and over again. That it is disrespectful to go to someone with more knowledge than you without even doing a google search and bringing something to the discussion.

Anyway, these are some of the things I learned. I’m curious what the knowledge gap is between those of us in the industry and those just finishing college. To that end, I’m hosting a zoom call on Thursday, August 19th at 8 PM eastern. I’ll probably have some slides prepared, but I’m hoping that most of the session is about Q&A with questions people bring. All you need to do is join the zoom.

Pensive Ruminations about Thinking

photo by Jesse Martini

A few weeks ago a coworker implanted an idea in my brain about this concept of Second Brain. The notion is that the brain is being used in ways it wasn’t designed for and we have a ton of tools at the ready to do more than ever. The notion that we are bound by the limits of our brains is somewhat false. Knowledge and ability goes beyond the our bodies now. With the internet and the use of other information, it is possible to accomplish a bunch even without being able to remember everything.

The link above is for a specific methodology of coming to a second brain. The truth is there is more than one way to do it, and the person who is teaching that class’s big claim to fame is that class. Is organizing how to teach others to organize really success? I’m skeptical. The class that he is offering is in the multiple thousand dollar range and fills up, but I’m not willing to spend that much to learn to figure out my life.

Instead I’ve decided to start reading and figuring out things for myself. I’ve started with a book called The Extended Mind. I’m still working my way through it, but already I’m enraptured with the ideas in it. The notion that our brain does not end at the organ in our heads. The fact that our brain is an organ and a muscle like we’ve all been taught. These are all compelling notions. Taking this further than the book has so far, the mind extends to all of the knowledge that is available to us. This includes all the people we know. Our knowledge then is a shared knowledge. It makes me wonder if by the definition of the book, are humans really just one brain working together? I’m not yet finished with the book (really just starting), so these are all unfinished thoughts. I don’t have a full answer to what I think about the book and this notion yet.

What I do have a thought on is the new program that I found with a little bit of searching. It’s called Obsidian. Basically it’s what I’ve been looking for but without knowing I was looking for. It is a visual representation of the notes on your computer formed in markdown. It can sync between multiple devices (though you do have to remember to save, which is annoying). You can easily link between notes and jump to other notes. You can see the notes in a graph view and see the ones that are connected. It was created as a way to foster connection between thoughts and allow for more of this second brain stuff to exist. It stores all the data in Markdown files on disk so it is accessible at any time.

I’m definitely not using it as efficiently as I could be and there definitely is a lot of work for me to do get the organization the way I need it to be, but I’m loving it so far. Unlike Bear, it allows for complete stylesheet customization. This allows you to shoot yourself in the foot or create some cool additional features if you want. There are a whole list of external plugins as well, because it is just javascript under the hood. This is my tool. Now I just need to figure out how to get all of my old notes from Day One over and start making things better.

Also of note, because it lets me override styles, I am using my favorite MonoLisa, which allows me to do very cool arrows and various other ligatures that I really like.

Unknown how the use of this program will help me in the long run, but maybe this will allow me to create more than just my own thoughts. Maybe someday I will be able to pass on my second brain to my family and anyone else who wants it. Pretty excited about figuring all of this out.

WebDriverJs and Chromedriver

If you’re not familiar with WebDriver, perhaps you should be (if you’re a programmer). It’s a tool used for performing user tests on websites. I’ve been working on a project for testing some websites with Chromedriver, the chrome implementation of WebDriver. Once you have the driver up and running you need a way to send it commands to get it to do user actions. Chromedriver responds to simple REST requests, which, of course can be issued through JavaScript. This leads to WebDriverJS, a simple implementation of the REST protocol for WebDriver. You can use it server side, with something like node. Or you can use it client side, within the browser.

Here’s where the plot thickened for me. Normally I used to start chromedriver directly:
https://gist.github.com/2885890.js?file=old_way.sh

Once I had the server up and running I wanted to test
https://gist.github.com/2885890.js?file=run-driver(wrong).js
with the html:
https://gist.github.com/2885890.js?file=wd_test.html

I spent several days trying to get this to work. I had no success. I searched the interwebs, and came up with nothing. The solution is simple, but was not apparent. You need to run chromedriver through the webdriver shell.

Here’s the command line:
https://gist.github.com/2885890.js?file=with_selenium.sh

You also have to modify the connection javascript, the run-driver.js should how look the following:
https://gist.github.com/2885890.js?file=run-driver.js

These pieces put together should allow you to control your chromedriver.

GoodBye GoDaddy

After the whole SOPA debacle, I decided I was done with GoDaddy. Their site has always been crap. It’s hard to use and figuring stuff out sometimes takes a call to their tech support. On top of that, they had been starting to raise their prices. They used to be one of the cheapest registrars on the internet, now they were charging significantly more than other registrars.

I have been using Dynadot for a bit as they were about a dollar cheaper than GoDaddy and The Brooks Review recommended them.

As of today it is official. All my domains are gone from GoDaddy. For various reasons that I hope to explain over the next year, I have 25 or so domains. The 21 that were at GoDaddy have now been moved to Dynadot. I’m looking forward to having an easier time administering them, and spending less on them in general.

iPhone 4S Setup, a post Steve Apple

I’m sad to say that the whole process of upgrading to an iPhone 4S (or 4 Steve as some crazy analysts have been calling it), has been more difficult than I would have expected. I’ll admit that I didn’t take the most conventional route to set this phone up, but my experience has not been pleasant. I feel this is a bad sign for a post Steve Apple.

Here’s my situation. I’ve been running an original Edge based iPhone 16 GB for the past 3+ years. I was waiting for the next new iPhone to come out so I could grab one. I was very excited for the announcement of the iPhone 4S, and unlike everyone in the media, I was not disappointed. I liked the design of the 4, and was happy that they were keeping it a little longer. I really have been wanting some more storage space. I like to have a lot of data on my phone, between my huge photo library and some videos to watch while commuting. So, all in all I was really excited about the new iPhone.

Fast forward, I decide not to rush out and grab it on day one because I wanted to make sure I could get my employee discount, seeing as I work for a company that has a close relationship with AT&T. I ordered it on Sunday. That translated to roughly a week and half delay from when they first started shipping. Still, not a huge deal. It would have been nicer to know when to expect the phone instead of having to check the AT&T website everyday to see if my items had arrived and shipped. To be fair, they sent me an email after the items shipped, but not until I had already been on their website and seen the tracking number.

So the phone arrives last night.

Since I ordered it from the AT&T store, I don’t have AppleCare+, because they didn’t have it when I ordered it. So I stopped by an Apple store on the way home, but they don’t carry +, so they advised me to call. I did, but they were closed by 8, despite the fact that a gentleman on the phone said they would be open until 9 PM PST (The representative I talked to on the phone this morning confirmed this). I tried back twice because I didn’t believe them, still closed. The guy at the store tells me that it’s not going to be an issue if I open my phone tonight, though (he was right about this part).

So I go home and unpack the phone and start setting it up. I’ve been reading on the web that there have been a few issues setting up a new phone based off an existing phones backup. To try and avoid these concerns, I initially decided to try and load my iPhone as a new device. I set it up, and got it running. Was playing around for a bit and then realized that I have tons of data on my phone, like SMS messages and other information.

I woke up early this morning and decided I’d try do it the other way. I went through the process of restoring the iPhone as my old phone. This process only took about 15 minutes and looked to be working pretty well, until I tried to use Siri to set a reminder. It said it couldn’t.

I had to call in this morning to AppleCare to get my AppleCare+ thing taken care of, so I figured I’d ask them about it. It seemed to be related to my iCloud settings. Couldn’t figure out exactly what it was, figured Apple would be a good option in finding an answer. Nope.

I first called in with my serial and before I could even say that I was calling to buy AppleCare+, the representative was on it, and said that I was eligible. I told her that was why I was calling, and she took my credit card information. I didn’t think of it until after, but she never stated how much she was going to charge me. I asked afterward, she said the product was $99, and there might be tax and it could be up to $5.25, but she didn’t think there was. She was VERY polite and kind, but not knowing what you are charging me does not seem right to me. I digress.

I told her I was having issues with iCloud. She walked me through the basic steps of setting up the backup and I kept getting an error message. She put me on hold several times throughout this process and was still unable to help me resolve my issues. Again, she was VERY polite, but did not seem to be able to help.

Finally she gives up and schedules me to talk to an iCloud specialist. Not a huge deal, but the first thing she tells me is that the specialist is going to call me, but when I ask her when, she tells me she doesn’t know. She put me on hold, again, and comes back several minutes later saying that I need to call a specialist. I say, that’s fine, what’s the number and when should I call? She puts me on hold again, only to come back and say that the system was down and she will have to call me back.

When I speak to the specialist, he was very kind, but did not seem to understand the problem I was having. We went through several phone calls, as he required me to have WiFi, but I was out and so did not have access to a WiFi connection.

In the end I spent some time debugging it. It was clear that reminders wouldn’t work if they were turned on in iCloud, but they would work just fine if iCloud sync was off. I went to go look at my calendars and that wasn’t working correctly either. When I went to my .mac account on my phone, asked me for my password. Once I entered that and turned on cloud syncing everything started working.

Also of note, Syncing with iCloud and backing up to iCloud are two very different things. Syncing means having your contacts and mail and calendar on the iCloud server. Backing up is a full device backup. A better explanation of that would have been helpful.

In the end I feel like there was just too much confusion with the setup. Most Apple products have been very plug and play. This device required some serious setup to get it the way I wanted, and it was not clear how to get there. I’m troubled because I’m pretty sure Steve would have taken some peoples jobs over how bad this process is and I’m not convinced Tim Cook has the same mentality.