WordPress Front End Application and Custom Admin Dashboard

From: “Lindsay Brown” <lbrown@denotetoday.com>
To: “Client with a private GitHub Repository” <client@co.com>
Subject: WordPress Inthenews – Merge to Master?

Hi Client,

I pushed the finished WordPress site to staging on December 5th. Have you been able to view it yet? In case you have not, I pasted some screenshots below which basically provide you with a tour of the admin dashboard and the public-facing responsive, flexible grid.

I have since upgraded the 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 the below looks okay, I would be happy to merge to master and make sure “client@co.com” can log in using a password that is 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 other Co staff would log in by going to https://co.com/inthenews/login.

The only user who can create new users and update plugins is you, the administrator user, client@co.com. 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.

By the way, 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.

News Card screen:
The Edit | Trash | View submenu items appear when you or an editor user hover over or touch the title. 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).

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 gives brief instructions for each field.

or instructions are just above the field.

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. 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.

Back on the Add or 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):

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

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

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 deals with removing “.html” from “https://co.com/inthenews.html.”

Thank you and I hope your holidays are going well,

Lindsay

Lindsay Brown
(202) 555-5555
denotetoday.com

Angular 2 Photo Website Preview

View the in-progress code and preview for my Angular 2/TypeScript website that contains a carousel.

Here’s a version with a carousel that uses Bootstrap styling and has input controls on the previous and next chevrons.

This version’s carousel is powered by CSS.

These Plunker versions have a consolidated file structure with fewer folders than the actual application has. I will publish the actual website on Azure web services. In the Plunker versions, the template and styling are contained in each component decorator. Also, the SCSS is absent, as well as my app’s compiled es2015 JavaScript…and the gulpfile.js.

TypeScript Configuration Troubles – Developers Unite

Update on April 28, 2016: Thank you Dave Ceddia of Angularity for your emailed advice that I follow my plan B outlined at the bottom of this post: start my build from scratch by writing my own gulpfile.js. 

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. The compilation problems that affected me and other developers world-wide include the four headlines below. I was successful at fixing three out of four of them. As always, I welcome comments that could point me toward a solution:

error TS2304 is TypeScript compilation-related

https://github.com/Microsoft/TypeScript/issues/2192

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 there is no such file named gulpfile.js in it!

Error on command line:

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

Message:

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 parantheses.

/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'.

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: https://github.com/angular/angular/issues/5746#issuecomment-215327528

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

The –save-dev flag makes sure the npm package gets written to the package.json.

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.

Upgrading the whole Modern Web Dev build

I updated the entire Modern Web Dev package.json from https://github.com/dsebastien/modernWebDevBuild/blob/master/package.json, then ran jspm init (the default module loader for this project), then I ran gulp clean, then gulp, then gulp serve. My project was served 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 simpatico 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, for my first “shippable” 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 https://angular.io/docs/ts/latest/quickstart.html.

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

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 includes Flexbox, but the one on ntpep.org does not.

If the interactive map does not appear in this space, your browser needs to be updated. Please view the map on ntpep.org 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.

This YouTube playlist includes 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.

View, fork, and pull request the map’s code from my GitHub account: https://github.com/LindsayBrown81/exploreMapPy

A summary of this Meetup event: http://www.meetup.com/Ladies-Who-Code-Washington-DC/events/225259705/

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

Wouldn’t it be such a timesaver for coders seeking technical guidance if every instructional article or blog post included the following preliminary information in a header of some sort?

-Prerequisite knowledge
-Word count and estimation of the article’s read time

Prerequisite knowledge
Prerequisite knowledge is the knowledge a reader must already have in order to understand your article. Stating this upfront allows a reader to gauge the risk of wasting their time by reading on. This is being respectful of your audience’s time while letting them make the decision. The good news is that such courtesy statements are not terribly lacking across the technical learning sites, so I am optimistic it will become a stylistic writing convention soon.

Avoid being condescending and discouraging to your audience by avoiding all forms of the word “simple” in your knowledge-imparting language.

There is a second reason to list prerequisite knowledge up front. It has to do with being respectful of your audience’s intellectual capability. If a writer skips explicitly stating the concepts or terms with which the readers should already be familiar, the writer risks frustrating and alienating them by accidentally behaving like a presumptive, myopic, haughty, arrogant, jerk.

Just a quick segue close to that point: avoid being condescending and discouraging to your audience by avoiding all forms of the word “simple” in your knowledge-imparting language. This applies not just to the summary or header, but also throughout every sentence you ever write which purports to help others learn to code or solve a problem. If it were simple to them, they would not be seeking guidance from you. Be respectful, because what comes around goes around. No one, not even you, knows everything.

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 glorious rabbit hole of enlightenment may devour. This might be an honest oversight or a deliberate omission to avoid scaring off not-yet-hooked readers who only have n minutes to find an answer. Hmm. If only there were a way to summarize the selling points up front, disclose the duration, then offer an easy way for readers to bookmark the article for later. Psst! 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. If you are curious, you can find out your reading speed by taking the test at the link above.

In conclusion
Be respectful of your audience’s time and intelligence by including some courteous facts at the beginning of your post or article, and by not talking down to them.

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.

Update on June 11, 2016: A terrific example of vague word choice is demonstrated on my comment on this GitHub issue. I am making a pull request today which contains my proposed rewording of the instructions for this JSON coding challenge.

I am a photographer and journalist-turned-JavaScript Developer. I have an MA in Journalism from Napier University in Scotland, where one grammar mistake would warrant a fail for that assignment. Trust me as I declare: terrible grammar is inhibiting knowledge sharing in the software development industry.

Over the past two years, as I zigzagged along on my own haphazard piecemeal learning trajectory (thanks, Twitter!), I have read plenty of educational blog posts, Stackoverflow answers, 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 it. This is not just due to the complexity of the computer science concepts involved, but also due to poor quality writing.

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

– Vague word choice
– Poorly-constructed definitions that lack nouns
– 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 allows.

Include specific-enough words in your definitions and explanations, and you will save your audience the energy of asking questions 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 possibilities they will need to deduce.

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. Says who? Says me, an open-minded person who once said, “Oh, you make your coffee with milk? Fascinating! So, do you pour the milk straight into the top of your auto-drip coffee maker?”

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 an appropriate context!

But there’s more; for specific word choice is not all that matters…

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 for some classes (I will omit names when citing in order to 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 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 improved 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 when 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: http://www.yourdictionary.com/scope). 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.

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, the antecedent.

In Grammar, a pronoun is a word that takes the place of a noun (source: http://www.grammarbook.com/grammar/pronoun.asp). 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 in 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: http://www.merriam-webster.com/dictionary/antecedent).

“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 them 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 programming.

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

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

Set expectations near the beginning of anything you write that seeks to instruct, inform, or explain code. Is your piece a step-by-step guide? Is it safe for readers to assume that they can follow along and practice running the example code in the order in which it appears? Answer that briefly in the beginning.

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 gone wrong.

Avoid frustrating your readers by stating before code examples whether the following code is worth practicing and memorizing. If it is not, give fair warning so that your reader does not devote ten or 20 or even 60 minutes to studying its every detail, nook and cranny, and burning it deep into their memory for no good reason.

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 README.md 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.