One of my goals at work for the past month has teen driving efforts to improve our internal documentation for front-end developers. It would have been easier undoubtedly to just rant about it at meetings and talk about grandiose projects. I chose rather to do something about it in my own work.
Pull requests. I used to just put a descriptive title and leave the description empty, sometimes linking to the original issue. A call-to-action came from my coworker, who asked me for a brief summary of changes so that it’s easier for him to understand what he was about to review. So, I put in some screen shots of any UI/UX changes, a few lines about background, something about the context for the pull request, and finally a short list of the main changes. In the last couple of weeks, I’ve started also adding links to any relevant documentation I wrote, such as backend API endpoints or anything in our product wiki.
Internal documentation. We use a popular open-source system to house our internal front-end documentation. So, I’ve made it a part of my workflow to document any backend API endpoints in our system. That way, some developer won’t curse my name and the day I discovered programming when they have to maintain or debug my code.
How-tos and repo documentation. Taking my coworker’s request further, I expanded any developer documentation that lives in the repository. This is usually either how to get started or how to implement a new feature. The effort spent on this (and README.md in tow) will hopefully mean that other developers will find it easier to get going with the codebase.
I wrote the original version of this piece, last year on Medium. This is an expanded and less guarded take.
I didn’t want to study software engineering in college. I first wanted to study English literature and drama. That wasn’t an option at home. So, I looked at the other things I had dreamed about since childhood – architecture. I put together a portfolio and applied to Bartlett School of Architecture in London. They hid the rejection letter from me and told me no. So, I fought them and the first compromise was computer-aided product design. I just wanted some art in whatever I studied.
There was none of that. It was all math, physics, and science.
Over the last couple of weeks, I have been working on a project to make Kivra’s web app ready for other languages than Swedish. It’s been a great deal of manual work, going through the codebase and moving strings to our copy repository.
This involved a lot of cross-checking and checking that the strings are being used or not. After a little while of using find/replace in Atom, I realized that this was going to take a long time.
So, I put together a little gist. That gist turned into a simple repo that I whipped together.
After customizing the repo with some tooling and npm options, it seemed like a good idea to generalize this into a boilerplate that I can reuse for other support systems or for my own projects.
I started listening to the Longform Podcast today and I noticed that they had this section underneath the player.
It’s similar, in functionality, to what you can do on YouTube by linking to specific points in the video, but it takes it further by providing direct links. It’s footnotes for the Web and I think it’s an ingenious way to help a listener focus on the podcast.
I’ll be starting this challenge tomorrow (Wednesday). I must admit that I feel a certain amount of professional shame by doing it, but there’s a conjoined sense of need to do so, too.
I’m at an uncomfortable juncture in my professional life as a developer. I have a whole lot of years of experience, but I look at job descriptions and I feel like that experience don’t align with them. It’s like that dream of showing up naked at your final high school exam, but you’re awake and it’s not a dream.
I didn’t make the right choices over the last 6 years in staying current with the latest technologies and picking the companies that would have ensured the right development of my craft. It’s uncomfortable and unavoidable.
So, doing this challenge for 100 days, along with working on my own app projects, is a way to get back on track.
Been in my situation? Mentored or known someone who has? I’d love to hear your pick-me-uppers in the comments!
I was searching for Twitter clients for the commandline the other day and I found Rainbowstream. It’s an excellent tool; this is some serious software right here. You can view images. Images! Images on the CLI…
I’ve been a web developer for the past eight years. My work has been primarily in PHP/MySQL and front-end development. I dabbled in journalism and data journalism in the last two years. I am now back in full-time development, but I still get itchy feet for open data and some investigations in data-driven stories.
I’m on Ubuntu 16.04, using Atom as my editor (I fall back into vi sometimesbecause it taste so gud) and nginx. I’m on PHP 7 and PostgreSQL for backend work.
It would be great to know you in the comments below. Introduce yourself and your dev stack. Let’s talk shop!