Interactive NTPEP Map – JavaScript, SVG, JSON, Python

NTPEP is the National Transportation Product Evaluation Program, a resource-pooling project for state Departments of Transportation run by my former employer AASHTO.

Here are four short paragraphs summarizing why I made this single page web application and how it works: README

This is the second version of the map. I added click functionality instead of hover, and a drop down menu by which users can select a transportation product type and then see those participating states turn white. Visit my GitHub account to see the complete code for this second version of the NTPEP map.

Please note that the implementation below uses Bootstrap for styling.


Ah, snap. Error loading map.

WordPress Front End Application and Custom Admin Dashboard

Below is an email I sent to a client after finishing the project I was hired to do. It demonstrates my ability to provide a static walk through of the UI using screenshots and clearly written descriptions and instructions. Note: I have changed the clients’ contact information to protect their privacy.

“Lindsay Brown” <>
To: “Clients with a private GitHub Repository” <>
Subject: Walk Through of WordPress InTheNews Page and Admin Dashboard

Good Morning, Client,

I pushed the finished WordPress admin dashboard and news cards web page to the staging branch on December 5th. Have you been able to review it yet? I would be happy to demo them to you using Google Screen Share at your earliest convenience. Meanwhile, I pasted some screenshots below which basically provide you with a tour of the finished admin dashboard and the finished public-facing responsive, flexible grid for the news cards.

I upgraded your WordPress site to v 4.7 and pushed that and some other admin dashboard customizations to the staging branch. The 4.7 upgrade does not change the look or functionality of the site.

If you do not have the time for a demo and the below looks okay, I would be happy to merge to master after receiving your approval.


Getting started:

Your user login is “” You can log in using a password that will be auto-generated when the site is deployed on the production server. You should change that password the first time you log in by clicking on “Users,” then scrolling down to the “Generate Password” button.

Once the live site is configured correctly, you and the other Co staff members will log in at

The only user who can create additional users and update plugins is you, the administrator user, There are three installed plugins: Advanced Custom Fields (v 4.4.11), Podamibe Custom User Gravatar (v 1.0.3), and WordPress Database Backup (v 2.3.1), which will email you a database backup once a week.

You will know when a plugin needs to be updated when you see the pink circular arrow icon appear in the left corner of the admin bar as shown in the screenshot below. Click on the icon to go to the update plugin page and follow the prompts from there.

Admin dashboard tour

News Card screen:

The Edit | Trash | View submenu items appear when you or an editor user hover over or touch the title of an individual news card. The rows’ default order is reverse chronological order (most recent on top). You can change the sorting order by clicking on each header (Title or Date). Clicking on the Title header will sort the news cards alphabetically.

Edit or Trash News Cards screen:

Category name is a drop down menu and publication date is a “date picker” (like a mini calendar) that pops up when you click in the field.

Add a News Card screen:

Very similar to the Edit or Trash a News Card screen except fields haven’t been filled in yet by any user and the “Preview Changes” button is simply a “Preview” button. Placeholder text provides brief instructions for each field.

Instructions are otherwise located just above the Publisher field and Image button.

Select Image screen:

Images need to be uploaded to the Media Library. The reason for keeping images on your own server is that images that sit on external websites are third party dependencies that you cannot control. Eventually they get moved to different URLs (I fixed a few that already have been) and the respective news card ends up with a missing picture icon in the corner of a mostly blank, gray news card. Fortunately, images that you upload into the Media Library are in your control; plus, they can be edited and cropped by clicking on the blue Edit Image link on the right side of the Select Image screen.

Edit Image screen:

To use the crop tool, click on the crop button all the way on the left (it will become darker, indicating it is active), then click and drag on the image to define the crop area, then click back on the crop tool again. The save button will then turn a brighter pink, meaning it can then be clicked.

Previewing a news card:

Back on the Add a News Card screen and also on the Edit or Trash News Cards screen, the news card preview button (upper right corner) will show you what the single news card you just worked on will look like at various screen sizes as you drag and resize your browser window. For example, the below screenshot shows a browser width of 1400px (each card column is narrow and so publisher and title cover four lines, and there is more white area under the image).

The preview below shows a browser width of 542px (the card column is wider and so publisher and title cover three lines as opposed to four, and there is less white area under the image).

Public-facing Web Page

The In the News Web Page:

The new WordPress public-facing web page looks almost identical to the original Laravel web page except now there is better centering and the View All News button has a white background that turns gray on hover like this:

If I missed anything, I’m just a phone call away. Please let me know if I can go ahead and merge this to the master branch. The original InTheNews web page will remain published until Sajad or someone in Dev Ops handles the redirect; i.e., removing “.html” from “”

Thank you and I hope you are enjoying your holidays!


Lindsay Brown
(202) 555-5555

Technical Writing Style Guide: Part 1 – Respect Your Audience

Prerequisite knowledge: 8th grade English reading ability
Word count: 522  Estimated read time: 1-2 minutes

Everyone deserves respect
You are an experienced software engineer or tech guru of some sort, and now you feel a sincere desire to share your knowledge with newer developers who need your guidance. This is a praiseworthy intention, but be mindful in how you take action, remembering the old English proverb “The road to hell was paved with good intentions.”

Two excellent premises to bear in mind while you write are to maintain a tone of respect for your audience’s knowledge level and respect your audience’s time.

Maintain a tone of respect

Respect your audience’s knowledge level by syncing with it
List prerequisite knowledge at the start of your article or post so that the readers can gauge whether they have the knowledge necessary to make sense of your lesson.  At the top of your article, explicitly state the general concepts or terms with which the readers should already be familiar.  If omitted, you risk either frustrating readers by taking them part way to understanding only to skip defining key terms; or, you risk patronizing readers by over-elaborating; either way, your tone may come across as presumptive, myopic, or arrogant.

Avoid being condescending and discouraging to your audience members who are newer to coding by avoiding the word “simple” when describing the solution.

Avoid being condescending and discouraging to your audience members who are newer to coding by avoiding the word “simple” when describing the solution. Remember that if it were simple, they would not be seeking guidance from you, nor would there be a burgeoning cottage industry on how to pass a coding interview. So, be respectful, because what comes around goes around. No one, not even you, knows everything.

Respect your audience’s time

Word count and estimation of the article’s read time
Busy readers often wonder, “Do I have the time to read this?” yet writers tend to omit an honest disclosure of how many minutes their wisdom-sharing words will likely devour. It is best to not draw in not-yet-hooked readers who only have n minutes to find an answer. Instead, summarize the selling points up front, along side an honest disclosure of your article’s duration, then offer an easy way for readers to bookmark the article for later: a call to action button! Bookmark me!

One subtle and popular way to hint at a longer read time is by stating something like “Grab some coffee and settle in.” This qualitative approach is easy, whereas quantifying an actual time range can get complicated due to your audience’s wide variety of reading speeds and comprehension levels. Just remember when estimating your article’s time range that technical writing is dense and typically requires readers to slow their natural reading speed in order to maintain comprehension. According to the results of the Staples-sponsored speed reading test, the average adult reads 300 words per minute; the average college student reads 450, and the average high level executive reads 575. Anyone can find out their reading speed by taking the test at the link above.

In conclusion
Be courteous and respectful of your audience’s knowledge level by including some prerequisite terms and by not talking down to them or speaking over their heads. Be respectful of your audience’s time by displaying a word count and/or estimated reading time at the beginning of your post or article.

Technical Writing Style Guide: Part 2 – Define Your Meaning

Prerequisite knowledge: 8th grade English reading ability
Word count: 1147  Estimated read time: 3 – 4 minutes

This blog post will address three critical-to-address, pervasive grammar mistakes that I have repeatedly observed across a myriad of instructional technical writings; specifically, in definitions and explanations of technical terms. The targeted audience is anyone who teaches, writes, or explains coding-related material.

Who am I to say?

I am a photographer and journalist-turned-JavaScript Developer. I have an Master of Arts in Journalism from Napier University in Scotland, where one grammar mistake would warrant a fail for an assignment. I am hereby authorized to declare: terrible grammar is inhibiting the transfer of knowledge across the software development industry!

Over the past two years, as I zigzagged along on my own haphazard learning trajectory (thanks, Twitter, for drawing me out to so many random tech seminars), I have read plenty of educational blog posts, Stackoverflow answers, framework documentation, and complete tutorials on JavaScript, web standards, and related technologies. Despite the plentitude of online learning resources, the learning curve is still forebodingly steep for anyone aiming to learn a language, framework, or tool by Googling and self-teaching it. This is not just due to the complexity of the computer science concepts involved, but also due to incomplete, poor quality writing and documentation.

The most critical-to-address, pervasive writing mistakes in technical documentation and explanations are:

1) Vague word choice
2) Poorly-constructed definitions that lack nouns
3) Overuse of pronouns

1) Vague word choice

Words with broad, general meanings fail to set context and constrain the meaning of a definition or explanation. Examples: Data is “a thing.” This function will “do something.” Vague word choice will lead imaginative learners to ask an onslaught of questions as wide as your word choice will allow.

Include specific-enough words in your definitions and explanations, and you will save your audience the energy of asking questions which they likely strained to refine. You will save yourself the energy of answering questions that seem to come from left field. Finally, specific word choice will save learners time by trimming down the possible solution paths they will need to evaluate or analyze.

A terrific example of vague word choice is tackled by my comment on this GitHub issue. In it, I propose rewording the instructions for this online coding camp’s JSON coding challenge.

This EnvatoTuts blog post written by Cho S. Kim emphasizes the importance of setting a specific-enough context with the right words while teaching abstract concepts.

He asks, “What is a data structure?” The typical smug reply of “data with structure” does not help the imaginative learner. Believe me, that phrase can be interpreted in a plethora of ways.

Cho avoids vagueness and draws an appropriate context when he explains, “A Set isn’t a thing; a Set is the name assigned to a particular way of organizing data. What’s equally important, a Set is created using objects.” Hats off to Cho for using specific word choice to convey the appropriate context!

But there’s more; for specific word choice is not all that has been lacking…

2) Poorly-constructed definitions that lack nouns

I have read numerous attempts at definitions that only describe a term’s use cases, behaviors, context, or relationship to other terminology, but fail to articulate what the term actually is. That is because the definition lacks a noun that gives meaning to all other words in the definition.

Example from an online coding school that charges students a fee for some classes (I will omit citing names so that I may openly criticize): “Directives are how we bind behavior to the view.” Although this statement contains specific word choice, it lacks a defining noun, and therefore the statement does not constrain meaning and set context; i.e., it does not tell the audience what a directive is not; for instance, that directives are not a glittery dust that AngularJS developers blow from the palm of their hand onto their screen after having just written a controller. A helpful, lucid definition of a directive is available on AngularJS’s official documentation: “At a high level, directives are markers on a DOM element (such as an attribute, element name, comment or CSS class) that tell AngularJS’s HTML compiler ($compile) to attach a specified behavior to that DOM element (e.g. via event listeners), or even to transform the DOM element and its children.” I would argue that this definition could be further strengthened by replacing “markers” with “annotations.”

A clear, legitimate definition typically includes the main noun within the first three words of the definition. Whenever you are writing about a technical term, quote the authoritative definition found on the technology’s official documentation before elaborating on it with your own words.

Poorly-constructed definitions that lack a key noun commonly start with “is when.” Beginning this way results in nothing more than an adverbial description of the term’s context, behavior, or effects. Example: “Scope is where a function can get executed.”

Poorly-constructed definitions that start with “is how” are likewise just adverbial descriptions of the term’s means, ways, or manners. Example: “Scope is how we determine where in our code a function can get executed.” (By the way, who does “we” refer to? Please avoid pronouns that refer to undefined subjects.)

Sometimes poorly-constructed definitions skip straight to the verb. Example: “Scope refers to the visibility of variables.” Due to the lack of a noun as subject, readers only know that scope is something that refers to the visibility of variables, but what? What is scope?

The following is an example of a properly-written definition of scope: “the region of program source in which an identifier is meaningful” (Source: Illuminating! Though I am not sure what region means.

Superior to that definition is Kyle Simpson’s definition of scope: “Scope is the set of rules that determines where and how a variable (identifier) can be looked-up” (Source: You Don’t Know JS: Scope & Closures by Kyle Simpson). Scope is not a thing; scope is a set of rules. Eureka!

3) Overuse of pronouns

Be sure to accurately and succinctly name all the pertinent nouns in your definition or explanation while avoiding using pronouns such as “it” and “we” unless the pronoun unmistakably refers to one obviously distinct noun, known in grammar as the antecedent.

In Grammar, a pronoun is a word that takes the place of a noun (source: Nouns and pronouns are either subjects that perform an action or objects that receive an action. Here is an example of properly using a pronoun: “Bob deployed the application to the cloud. He tested it there.” Because there are no other reasonable possibilities, it is obvious that “he” refers to “Bob,” “it” refers to “application,” and “there” refers to “cloud.”

As defined by Merriam-Webster’s dictionary, an antecedent is a substantive word, phrase, or clause whose denotation, i.e., literal meaning, is referred to by a pronoun (source:

“Bob” is the antecedent of “he,” “application” is the antecedent of “it,” and “cloud” is the antecedent of “there.”

Bearing in mind these concepts on clear pronoun usage and concise word choice, technical instructors who have slipped into the habit of stating, for example, that “we are parsing code,” would serve their audience better by rephrasing that to “the JavaScript engine is parsing code.”

If in spoken conversation you find yourself having difficulty articulating concepts about code without using pronouns such as “it” or “they,” consider using a laser pointer to clarify your meaning so that you can point it out to students as you explain “how these will get passed to it at the end of all of this.”

In conclusion

As a general courtesy to your coding colleagues, clients, mentees, and readers, remember that expressing your thoughts in complete sentences – replete with a subject and a predicate – will increase the likelihood that you will effectively convey your knowledge to your audience.

In order to facilitate better knowledge sharing across the tech industry, please avoid vague word choice, poorly-constructed definitions that lack nouns, and overuse of pronouns whenever you are writing instructions, guidance, definitions, or explanations about how to code.

Technical Writing Style Guide: Part 3 – Setting Expectations as You Instruct

Prerequisite knowledge: none
Word count: 212  Estimated read time: 1 minute

Attention technology teachers in the blogosphere and authors of technical documentation! Here is the third post of my three part style guide on technical writing. Set expectations near the beginning of anything you write that seeks to instruct, inform, or explain code. Is your article a step-by-step, follow-along guide? If so, is it safe for readers to assume that they can practice running the example code in the order in which it appears? Answer that briefly in the beginning. Like order of operations, order of instructions matter.

Be mindful not to misdirect readers by prefacing inserted code with language such as “This is what you could do” only to follow it with “but do not actually do that.”

Be mindful not to misdirect readers by prefacing inserted code with language such as “This is what you could do” only to follow it with “but do not actually do that.” Such introductory language leads your readers to believe that the following code is a solution that works. So they often take the time to copy and paste sample code into their text editor and test it out; but, as soon as they realize something is amiss in their console, they become confused and may waste a pitiful amount of time and effort scrutinizing where they have made a mistake.

Avoid frustrating your readers by stating in front of code snippets whether the following code is meant to compile and/or run, and is worth practicing and memorizing. If it is not, give fair warning so that your reader does not waste 10 or 20 …or even 60 minutes studying its every nook and cranny, troubleshooting it in painstaking detail, and accidentally burning it deep into their memory through repeated re-reading, only to learn later down the page that the code was never meant to work.

TypeScript Configuration Troubles – Developers Unite

After three long days of whack-a-mole’ing my Modern Web Dev build for my Angular 2/TypeScript/Sass/Gulp website project, it is launched again on my local server. Four compilation errors plagued me and other developers world-wide. I fixed three out of four of them. I welcome any comments over the next few days that could point me toward a solution on the one that is still broken. See first error below.

1) error TS2304 is TypeScript compilation-related

First thing first: the one left unfixed. The most recent error from my command line today, which resulted from my running the gulp serve command, centers around TypeScript compilation failing in my build. As advice via the link above suggests, I could call the compiler from the root directory, or pass in absolute paths. The absolute paths work-around is what I will try tomorrow. My initial thought was to change a line or two in the gulpfile.js, but this generated build is very complicated and, aye, there is no such file named gulpfile.js in it!

Error on command line:
[19:22:53] Error in plugin run-sequence

An error occured in task 'scripts-javascript-dist'.

app/pages/public-events/public-events.component.ts(6,36): error TS2307: Cannot find module '[filepath to typescript file].

app/pages/public-events/public-events.component.ts(16,13): error TS2304: Cannot find name 'Images'.

app/test/sanity_test.spec.ts(2,1): error TS2304: Cannot find name 'describe'.

app/test/sanity_test.spec.ts(3,2): error TS2304: Cannot find name 'it'.

app/test/sanity_test.spec.ts(4,3): error TS2304: Cannot find name 'expect'.

app/test/sanity_test.spec.ts(7,2): error TS2304: Cannot find name 'xit'.

app/test/sanity_test.spec.ts(8,3): error TS2304: Cannot find name 'expect'.

/Users/lindsaybrown/dev/Lynzphotos2016/node_modules/angular2/platform/browser.d.ts(77,90): error TS2304: Cannot find name 'Promise'.

/Users/lindsaybrown/dev/Lynzphotos2016/node_modules/angular2/src/core/application_ref.d.ts(83,60): error TS2304: Cannot find name 'Promise'.
X 5 more similar promise errors referencing different line numbers in the parentheses.

/Users/lindsaybrown/dev/Lynzphotos2016/node_modules/angular2/src/core/change_detection/differs/default_keyvalue_differ.d.ts(23,15):error TS2304: Cannot find name 'Map'.
X 8 more similar map errors of course referencing different file names and line numbers.

/Users/lindsaybrown/dev/Lynzphotos2016/node_modules/angular2/src/facade/collection.d.ts(2,25):error TS2304: Cannot find name 'SetConstructor'.

/Users/lindsaybrown/dev/Lynzphotos2016/node_modules/angular2/src/facade/collection.d.ts(1,25): error TS2304: Cannot find name 'MapConstructor'.

2) npm complains about peer dependencies

Here is my comment on this issue (#5746) on Angular’s GitHub account and the comments of others who chimed in with me:

Although this issue was closed on Angular’s repo, that does not mean it is fixed, as recent comments reflect. My error (pasted below) concerned the reflect-metadata dependency, but others’ concerned es6-promise, es6-shim, rxjs, and zone.js. NPM is referring to these dependencies as peer dependencies, although they are all required by Angular 2 in order to run an application. It is strange that they are referred to as peer dependencies and not just dependencies. The reflect-metadata API makes it possible for Angular 2 component decorators to work. They involve mapping and observables.

Error on my command line:
npm WARN angular2@2.0.0-beta.15 requires a peer of reflect-metadata@0.1.2 but none was installed

My get-it-to-run solution:
Lindsays-MacBook-Pro-2:Lynzphotos2016 lindsaybrown$ npm install reflect-metadata@0.1.3 --save-dev

Note: the --save-dev flag makes sure the npm package gets written to the package.json.

3) sass-node update

The first dependency that broke my Modern Web Dev build was my sass-node package not handling errors that I made as I played with my SCSS styling. I updated that package with npm-install node-sass@3.5.3 --save-dev.

4) Upgrading the whole Modern Web Dev build

I updated the entire Modern Web Dev package.json from, then ran jspm init (the default module loader for this project), then I ran gulp clean, then gulp, then gulp serve. My project is running on my local server but errors are still present. Feels like a fragile build to me, maybe due to my meddling with it, or maybe due to the challenge of any build keeping third party dependencies updated and compatible with one another.

To sum up…

I had no idea how many build configuration kinks still needed to be ironed out while Angular 2 is still in beta. Angular is open about the fact that they rely on third party packages/modules/dependencies. Granted, being that this is my first Angular 2 website, I could have tried writing a simpler gulpfile.js or even skipping the task runner and using just npm as outlined on

With that in mind, if this Modern Web Dev build breaks one more time, I will write my own, simpler gulpfile.js from scratch, and add each dependency using npm install [package-name] --save-dev.

Update on April 28, 2016: Thank you Dave Ceddia of Angularity for your emailed advice that I follow my plan B irregardless of any additional breaks: start my build from scratch by writing my own gulpfile.js.

Checking In

This is a status update regarding my job hunting.

After I went on some interviews in January, I realized what kind of tech job I really want. I spent February and March learning NodeJS by attending NodeDC meetups, making inspiring connections at the annual NationNode conference, and working my way slowly through LearnYouNode.

I have also been dissecting the Modern Web Dev build I used to scaffold the next version of my event photography website. Lynzphotos2016 is under development. I am writing it in TypeScript using the much-anticipated JavaScript framework, Angular 2. Babel will compile my TypeScript to es5. My task runner is Gulp. I am using Sass for my styling, so am writing my styling in a SCSS file, using mixins and variables. I am going to dabble in BEM and SuitCSS. Frankly, I am dabbling and exploring too many optional tools and methodologies in this build, hence my slow progress. I hope I am not being too hard on myself by calling my progress slow.

For greater detail about the build, about my thoughts on the naming convention, and to find out which learning resources have helped me along the way, check out my project’s on GitHub.

Further, I have refactored my NTPEP map in order to demonstrate that I can exercise closure. I have also taken Angular 2 tutorials, the main one being the Tour of Heroes which I pushed to GitHub. I have attended the DC OpenDataDay conference and taken smaller, unpublished tutorials on Plunkr and cloud9.

Every day I log my hours and summarize what I do in each session. I believe in Deliberate Practice, a learning methodology which entails stretching out of my comfort zone and challenging myself on new material in two sessions a day.

Interactive NTPEP Map – JavaScript, SVG, JSON, Python

NTPEP is the National Transportation Product Evaluation Program, a resource-pooling project for state Departments of Transportation run by my former employer AASHTO.

Here are four short paragraphs summarizing why I made this single page web application and how it works: README

This is the second version of the map. I added click functionality instead of hover, and a drop down menu by which users can select a transportation product type and then see those participating states turn white. Visit my GitHub account to see the complete code for this second version of the NTPEP map.

Please note that the implementation below uses Flexbox for styling.


If the interactive map does not appear in this space, your browser needs to be updated. Please view the map on instead.

Video: My Interactive Map with Python, JavaScript, SVG, JSON

I gave a presentation on my interactive map at Ladies Who Code – DC on September 21, 2015. Thank you, Jennifer Galvin, for recording this at the Sunlight Foundation in Washington, DC.

The player above will play this entire YouTube playlist. It is comprised of several three to nine minute-long videos. The video topics are:

  • an overview of how my single-page web application works,
  • a demonstration of the SVG coordinate system which drew the state shapes,
  • a discussion about JavaScript testing on UI elements,
  • a look at the JSON structure and the Python script that wrote it,
  • ideas on how to automate updating the contact information;
  • and lastly, a challenge posed by Liz Merkhofer to show only the contact information for the individual(s) who serve as the point of contact for the one product type that is selected in the drop down menu.

If you are interested in trying to solve Liz’s challenge, you may view and fork or pull the map’s code from my GitHub account:

The official Meetup summary for this event: