Atlantic Business Technologies, Inc.

Author: Jon Karnofsky

  • The 5 Best WordPress Plugins for Large Content Websites

    The 5 Best WordPress Plugins for Large Content Websites

    Even though one of ABT’s core offerings is custom development, I have always advocated for not reinventing the wheel if necessary. So I’ve come across a number of plugins that I have since found indispensable in managing a large WordPress site – and our site isn’t even nearly as large as others! Here are the five top WordPress plugins I recommend for pretty much anybody. These may still be useful if you’ve got a 5-10 page site – but if you’ve got hundreds or thousands of pages and posts, I think these are badass!

    Why did I write this? I’ve been the primary person responsible for the Atlantic BT website for more than a year now. By that, I don’t mean I do the development or write every single piece of content, but I am the main admin of the website. Similar to the role many of our clients are in, or you may be. I thought an article that isn’t based on popularity or what sells, but instead first hand practical use, would be helpful to you.

    ABT does not get any referral fees or compensation, this is all just personal opinion by the author.

    Yoast SEO Premium

    Yoast is one of those plugins that it seems like everyone uses. Like, everyone. And for good reason – when it comes to managing SEO it’s got a great set of features and admin user experience too. I tried the premium version out for some of the features, and it’s here to stay. I won’t go into the free version features, just some of the premium ones that make it worth it.

    Redirect Management

    The feature I love the best is the redirect management. I try to stay up to date on making sure we don’t have any internal 404 links, and this helps a ton. You can manually add any redirects that you want – so if you’re doing spring-cleaning on your content, it’s really easy to make sure no one hits a dead end. But even better is the real-time redirect updates. If you change the URL of a page, and you hit update, Yoast will automatically create that redirect for you. Also, if you trash an old page that’s not relevant anymore, Yoast will ask if you want to redirect or create a 410 status code for that URL. (A 410 status code is how Google and the rest of the internet knows the page used to exist and was purposed removed).

    Search Engine Previews

    When you’re editing a page or post, Yoast gives you a preview of how a search result will look based on the title, excerpt, etc. With premium, you can also see previews of social shares for Facebook and Twitter, and even override the info each if you want to tweak it. It’s not a necessity to do so on every page, but if you’re heavy into social media, it’s a great option.

    I haven’t really dug into the Yoast AI implementation, since we tend to use ChatGPT more regularly. And while there is a feature in premium where Yoast offers suggestions to link to other pages on your site, the next plugin is much better for that.

    LinkWhisper

    I was looking for an AI driven tool to recommend links to other pages on our site, beyond what Yoast was doing. I came across LinkWhisper and got that and a lot more.

    Internal Linking

    You’re able to generate more internal linking in a few ways. You can edit a page or post, and LinkWhisper will look at the content on the page and recommend links to other pages. From the “All Posts” or “All Pages” list you can also get a list of suggestions to link to that page. There are also some nice reports to give you insight to how much linking you’re doing all around.

    Auto Linking

    I think “auto linking” is the coolest feature. As an example, I could add “best WordPress plugins” to auto-link to this post. If that exact phrase appears in any existing content, or any new content, the link to this post will automatically happen!

    Error Report and URL Changer

    The last features which has helped a ton in regularly cleaning up SEO is the error report and the URL changer. The error report is a great way to find and fix broken links (both internal and external). The URL changer compliments Yoast Premium’s redirect feature wonderfully. Yoast will make sure that any existing links to old content don’t break. But it’s still best practice to not go through redirects and change the content to link to the new URLs. This is where LinkWhisper comes in. You add the old and new URLs, and instantly all your content is updated.

    GTM4WP – A Google Tag Manager (GTM) plugin for WordPress

    If you use Google Tag Manager, I think this plugin is a must. By putting in your GTM code, the plugin will add the necessary script on your site and has a lot of adjustments. There are a ton of settings which can get pretty technical that I won’t go into, but there are two main aspects that make this completely worth it.

    In “Basic Data / Posts”, you can very quickly add information that go to GTM (which you’d probably want to push through to Google Analytics). Info like post author, title, categories, post type; if you’re big into analytics, and you want to break down the analytics in a number of ways, this makes it easy.

    In “Basic Data / Visitors” is the ability to include data such as “is the user logged into the admin” and user roles. This becomes extremely valuable when you exclude, or make separate GA audiences for, logged in content editors and admin. Atlantic BT employees end up browsing the site a ton, including myself. I don’t want that traffic in our Google Analytics, though. With this feature, we can prevent our analytics from being inflated by our ourselves!

    Find My Blocks!

    This one is a little more technical, and more useful on sites like the ones Atlantic BT creates, where we build custom blocks. We recently did an audit to find out which custom blocks weren’t being used or catalog where they were. This is a free, light plugin which made that audit easy.

    Whether you’re doing an audit, or you know you used a block (somewhere!) and can’t remember where – this plugin is a winner. 

    WP All Import & WP All Export

    If you’ve got hundreds or thousands of posts and pages, and you like working in spreadsheets, this plugin pair is indispensable. Trying to export information from WordPress using the default tools is… underwhelming. These plugins allow creating CSV (and other) files customized to the fields you care about. You can save templates and really control what gets imported so you don’t incorrectly overwrite things.

    If you’re in marketing and deal with SEO, exporting everything is wonderful so you can wholistically view your metadata and targeted keywords. Then you can work through your strategy in Excel or Google Sheets. If you’re going through a content audit or need to make bulk content fixes, the content field is something which is available for exports and imports too.

  • Working with an Agency is like a Fine Dining Experience: An Analogy to Explain Project Expectations And Interactions

    Working with an Agency is like a Fine Dining Experience: An Analogy to Explain Project Expectations And Interactions

    In two previous posts, I compared 1) website planning and development with custom house building, and 2) website maintenance with owning a vehicle. 

    In this post, I correlate the fine dining experience to working with an agency who is building your custom website or web application. This will make fewer technical correlations, but instead focus more on the people and process involved in bringing your project to life. And yes, I did make myself hungry while writing this article.

    Getting Seated

    You walk into the restaurant. The atmosphere is calm, the lighting is warm and soft, and you approach the host. There’s a short introduction, and they make you feel welcome. Maybe you made reservations earlier, but maybe not. If not, you put your name on the list and relax in the lobby. At some point (now or later), the host calls your name, and you make your way to the table. They inform you who will be your server for the evening, and soon that person arrives.

    Surprisingly, the sales process can and should follow a similar path. Once you reach out to a vendor and you’re introduced to a sales representative, hopefully you feel at ease. Sure, you’re having discussions about schedule, scope, and budget when planning a project (which doesn’t happen while waiting in the lobby for your table), but you’re learning if your companies are a fit. It’s clear you’ve found a vendor who understands your needs, cares about your success, and budgets align. Eventually a contract is agreed upon, you’re assigned team members, and a kickoff meeting is occurs.

    What’s on the Menu?

    With fine dining, there are a lot of interactions with staff once you are at your table. Many of them are with your server. To start, water is brought to the table and drink orders are taken. While the server gets your drinks from the bartender, you start browsing the menu. Your drinks arrive, and you have questions about the menu. The server has answers to most, but they go and ask the chef about one particular detail. 

    It’s a multi-course meal, so you put in appetizer orders while you think more about the entree. A sommelier arrives, and they discuss with you the varieties of wine that pair well with the meals you’re considering. Your party discusses everyone’s ideas, you ask a few last questions of the server, and they take your order.

    Discovery and design phases of web development also include many meetings and conversations. Many. Your digital project manager is going to be your point person throughout the project. They’ll facilitate meetings, answer your questions, and provide you updates. 

    In discovery, instead of you asking the bulk of the questions, it’s more common to provide the answers to many people as goals and requirements are identified. A UX researcher is a team member who is heavily involved in discovery. During the design phase, a UX/UI designer takes lead on visual design and a developer or architect provides technical design. It’s common for you to bring designs (UI mockups) to your team or stakeholders for review. Eventually, everything is approved, and the development phase begins.

    Let’s Get Cooking

    Your order’s been placed – and the waiting begins. You’re not abandoned, but you have your drinks and the heavy decision making is complete, so you have some time for yourself and your party. The server still checks in with you, refills drinks as needed, and you may see other team members such as food runners who bring you the appetizer and later your salad.

    But there’s a lot more people involved with your meal. A line cook makes your appetizers and prepares your salad. In the meantime, the head chef is preparing the entree with the assistance of a saucier. Finally, a sous chef reviews your meal to make sure everything is absolutely perfect. Remember, you don’t get to see any of this! 

    It’s honestly the same in web development, except this process takes weeks or months – not minutes or hours. You’ve reviewed wireframes, mockups, and data design documents, but now your website is being developed behind the scenes. It can be difficult to have no tangible progress for a while after so much engagement. Eventually, the digital project manager will schedule demonstrations or screenshare progress during status meetings. 

    The team, meanwhile, is busy. Back end and front end developers are creating the code base and building features. Every feature has to be developed, including code reviews by other developers. Cloud engineers work with developers to set up deployments. Quality assurance team members are testing the site throughout against acceptance criteria. Soon enough (okay, maybe not soon enough), the website is ready to be launched!

    The Meal Arrives

    Your meal arrives. Appetizer and salad plates have been cleared, food runners place the plates in front of you, and your server gets a ramekin of sauce you realize you didn’t ask for earlier. The fanfare is quick, and then you’re free to dig in. Shortly after, your server checks in again making sure everything’s as expected. Later, while you’re still enjoying the meal, the house manager or general manager stops by too. The staff may have completed most of the work, but you still feel taken care of.

    Launch day for your website is a big deal. Your old website is taken down and the new one is made available to the public. There’s lots of communication and excitement. A couple of small bugs are found and resolved quickly. Your digital project manager continues to be on point and coordinate with the team as you provide positive feedback, find a few problems, and maybe ask for a couple of small changes you didn’t realize you wanted before. It’s also common that your original salesperson, or an executive, also checks in with you to make sure your website and experience with the team are both satisfactory.

    You Don’t Leave After the Meal Arrives

    You sit back, your entree devoured. Hopefully, no one at your table unbuttons their top pants button. This is a fine meal, at a fine restaurant, in fine company – you don’t have to leave immediately! You decide to have a cup of coffee, or an after dinner drink. The server mentions a few special desserts that are available, and one of them is too good to pass up. 

    Your website has been up and running, launch announcements have been posted, and you and your team are focused back on other company initiatives. That doesn’t mean you abandon the website though. You have some articles planned out to add over the next few months. You and your staff, now really using the website regularly, have a few ideas for new features. Plus, the website needs regular updates and maintenance for security purposes and to keep it from getting out of date.

    What Doesn’t Fit

    So far, this article is more around experience than specific technical aspects of development, most of the comparisons work reasonably well. However, there are a few areas that don’t line up.

    Cloud Hosting. We can draw direct comparisons of developers with line cooks, and sous and head chefs with lead devs and quality assurance, but there’s not a great correlation with cloud engineering. If the meal is the website, there’s no food correlation to cloud hosting engineers – no one really in charge of the building, security, and repairing of cookware and plates. Sure, a general manager might be in charge of locking up the building and ordering or replacing cookware – but no one is crafting individual plates or creating individual access policies for the pots.

    Content. With a dining experience, after you’ve decided what you want to eat, your job is complete (except for eating). If your website is a large content website, however, you may have a significant responsibility – adding content. Depending on the technology and budget, the vendor may be able to build the entire site without your assistance. Honestly, this is rare. You likely have new pages you want to write, older content to clean up, and some older web pages to delete. It may be more efficient or cost effective to have your staff learn and build the pages themselves. No restaurant is going to let you into the kitchen in order to do some of the cooking yourself!

    Payment. One other departure comparing a fine meal with custom development is how payment is handled. With a meal, it’s a single evening that’s paid for in full after all services are rendered. Vendor relationships are different, and web development projects are larger, so an invoicing schedule is usually agreed upon as part of the contract.

    A Restaurant You Never Leave?

    I think it’s important here to wrap up by calling attention to the fact that the website launch doesn’t correlate to the end of a fine dining experience but rather the middle. And honestly, if you have a good relationship with your vendor and understand that a website isn’t a product but a service, that website launch may fall in the very early part of a long endeavor spanning many years.

    And lastly, even though it doesn’t feel like it while you’re at the restaurant, you will need to eat again. A well developed website with ongoing maintenance can last a long time but not forever!

    The Series Is Complete

    I hope this article and the others in the series help to provide you with more insightful context for your next website or web application project, and maybe liaise better with the vendor.  It’s been enjoyable to map out the complexities of web development with more common and relatable experiences. 

    I hope your next project is with Atlantic BT, but even if it’s with another agency – I hope your home building, car maintenance, fine dining adventure of custom web development goes extremely well!

  • Is a discovery process necessary for development projects?

    Is a discovery process necessary for development projects?

    Most people will agree there needs to be some level of planning before a project begins. But some may need convincing on spending thousands of dollars for what seems like a simple planning process. 

    A useful discovery process will go beyond standard timelines, budgets, and technology planning. In fact, a discovery is often needed to get to the root of the problem.

    Discoveries separate “core issues” from “nice to haves”. 

    The planning phase of a project should include the definition of what needs to be done – from which everything else proceeds. However, we often find differing perspectives on the definition of “what needs to be done.”

    Failing to fully understand desired outcomes can lead to unfavorable results. Scope creep could lead to budget and timeline overages. There’s a chance you’ll end up solving a problem that wasn’t the core issue. 

    Following a structured discovery process can ensure all of your bases are covered.

    The Discovery Pyramid ensures a full-picture diagnosis.

    At Atlantic BT, we like to describe our proven process in terms of the Discovery Pyramid. Each piece of this pyramid covers a crucial aspect of the total definition of the problem; skipping any one can negatively impact a project’s success.

    The key focus areas of the Discovery Pyramid are:

    Business Objectives – Determine the high-level business need that must be addressed, in terms of impact on sales, operational efficiency, market share, etc. This step also includes key objectives and constraints. Understanding the true business objectives sets the context and north star for further decision-making.

    Typical activities and deliverables include:

    User Research – These activities seek to understand your customer base, target audience, and/or key users, including their wants, needs, pain points and behavior patterns. Research is essential to providing a solution that truly meets user requirements, thus boosting customer satisfaction. 

    Typical activities include:

    • User Interviews
    • Persona workshop
    • Review client user data / market research
    • User workflows workshop

    Resulting deliverables typically include:

    • User Personas
    • User Journey Map or Service Blueprint (for complex workflows)

    Content & Design – An application is meant to deliver content and provide an interface for interaction with your firm. Content is the reason folks visit your site and content drives search engine results. Solid content and the design that delivers it go hand in hand. (“Design” meaning strategy, not visual mockups).  Marketing sites focus heavily in this area and may require extra steps.

    Typical activities include:

    Resulting deliverables typically include:

    Features & Functionality – Define all the details about how an application will deliver content, enable action, and combine with the design to meet user needs and deliver an outstanding experience. Ecommerce sites and business applications focus heavily in the features and functionality area.

    Typical activities include:

    Resulting deliverables typically include:

    Technical Solution – The needs and constraints determined from the above activities inform the technical solution. We’ll also need to review the technical audit of the existing solution, assess any integrations, and review your in-house skills and support abilities. From there, we create recommendations of technology base, platform, and services that meet needs cost-effectively. 

    Typical activities include:

    • System integration analysis
    • Code / database review

    Resulting deliverables typically include:

    What happens when you don’t follow the discovery process?

    We are often approached by folks that describe their needs starting in the middle of the pyramid: “we need a site redesign” or “I need to build this functionality”. While we can certainly start there, more context in the surrounding areas provides a more effective solution, thus we always back up to cover previous sections of the pyramid. 

    For example, a website redesign in support of expanding market reach requires a focus on search engine optimization. If the same site redesign was driven by an aging back-end platform, it may require a more extensive technical assessment and data migration plan. 

    We’ve also seen instances of clients asking for a redesign, thinking they would need web design and information architecture help. It turns out, most of the design work was around rethinking interactions, which ends up being a software development project.

    Discoveries should always precede solutions.

    All of the discovery steps focus on the why and what questions, rather than the how. In UX terms, they lie in the problem space rather than the solution space; you have to fully understand the problem before you can come up with the best solution. 

    Try to keep an open mind when going into projects. You may feel you’ve already diagnosed the core issue and know exactly what work is needed, but a third party can help shed some much needed light on the problem at hand. This level of focus and understanding will set you up for success in the development phase.

  • Maintaining a Website is like Owning a Car: An Analogy to Help Website Maintenance Make Sense

    Maintaining a Website is like Owning a Car: An Analogy to Help Website Maintenance Make Sense

    In the previous post, I discussed how the planning and development of a custom website can be similar to having a custom house designed and built. The analogy works in many ways, particularly in the planning and designing phases, but it’s not a perfect analogy.

    In this post, I’ll correlate website maintenance and ongoing development with owning a car. Keeping an application “purring like a kitten” takes effort, and I also won’t leave out aspects of digital upkeep that just don’t make sense with car terminology.

    When you’re done, the last post in the series compares the experience with your vendor to a fine dining experience.

    Keeping Fuel in the Tank

    Visiting the gas station is probably the most ubiquitous aspect of owning a car, unless the sole purpose of the vehicle is keeping it on a pedestal for viewing only. With a website, the same case can be made for hosting. Server or cloud hosting is foundational for a site to be usable. And similar to a car that may be driven more or less in a month, hosting costs can fluctuate – particularly from high or unexpected amounts of traffic.  (Although we want web traffic, we don’t want car traffic.)

    With a website that your users (or future customers) depend on, someone needs to be monitoring that hosting. A common offering these days is the Managed Service Provider (MSP). Picture this as a dedicated fueling crew, keeping the gas and fluids topped off. With the monitoring and ownership of an MSP, it could be said they also maintain and protect your garage and driveway, which can be compared to how your site reaches the rest of the internet.

    Maintenance Every 5,000 Users or 3 Months, Whichever Comes First

    No, not really every 5,000 users. But maintenance should be performed at least every 3 months. You may fuel your car regularly, but you also need oil changes and other regular maintenance items. Hosting on its own isn’t enough. 

    Code libraries and software versions need updates. If your site uses a Content Management System, those platforms also require regular updates. Code needs love just like your car. Your team of mechanics (development team) should perform these regularly.

    Sometimes these updates can cause small unexpected changes to the site, and fixing those are usually part of ongoing maintenance. It could be considered professional detailing whenever you bring in your site for maintenance. Keep it shiny! If you don’t perform regular updates, issues can build and compound. This is what we refer to as technical debt. 

    But Wait, I Want Something New On My Site

    We haven’t even gotten to new development yet – it’s all been upkeep. Yup, that’s on purpose. Would you spend money to upgrade a car you don’t even bring in for maintenance? I doubt it. New features don’t correlate to owning a car quite as well – but maybe at some point you want a custom paint job or to upgrade the console. 

    In my experience, it’s pretty uncommon that someone builds and launches a brand new site and then never wants anything to change. The process of a new feature for your car or your website is roughly the same: you talk to someone about what you want, provide some detail, get an estimate or quote, you approve the work, the work is completed, and you’re good to go. Where does website development beat out vehicle improvement? You don’t have to drop your website off and rely on another one while the work is being done.

    Lifespan & Resale Value

    Just like a car, your web application will have a longer lifespan if it’s better maintained. You might drive daily and reliably for 8 years, but if you never take it to the mechanic, the life span of your car is going to be shorter. If you let technical debt build and build, there can be a point that it would be cheaper to rebuild a new site than upgrade and fix the current one. There may not be “resale value” in a web application, but in five to ten years when you’re ready for a new one, the cost of building a new one will be lower if it’s been cared for. 

    I’ve known people who drove cars to the absolute maximum end of a car’s lifespan, spending as little money as possible on maintenance and upkeep. And yes, that’s an option with a website. However, as a website that presents your brand, brings in customers, and is possibly part of your employee’s workflow – it’s not going to end well.

    Where The Car Analogy Screeches to a Halt

    As you can see, there are a lot of similarities between owning a website and a car. But not everything fits.

    The most important difference? A website isn’t a product. There’s a reason we’re not discussing how buying a car is like building a site – it’s not. Almost all cars are manufactured, with certain options to choose from, in very specific configurations. A website simply isn’t a thing you buy, it’s really a service that you (with a development crew) build.

    Another difference is with a website, new technologies (or just time) can uncover vulnerabilities in code. This is why updates to libraries are important, as they’re where those vulnerabilities get fixed. Every time you bring your car in for an oil change, you’re not also changing the locks and reinforcing the windows. There typically aren’t new advances in car theft that you need maintenance every few months to prevent. However, even this is changing given the amount of digital components in vehicles, such as recent stories of key fobs being maliciously replicated.

    Problems or bugs will occur on a website. It’s reasonable to assume or hope a car won’t have any problems or recalls for the first couple years. Bugs will happen on a website. I promise. With a car, there’s typically a single operator (driver). On a site? Thousands of visitors with unique combinations of browsers, operation systems, hardware, and digital savviness are using your application. It’s impossible to guarantee every aspect of a site will work all of the time for everyone.

    There’s also not a good vehicle comparison to deployments. Deployments are when a site is first launched, but also any time code or hosting changes are made. Possibly driving the car off the lot is equivalent to the initial deployment of a new website, but other than that? I suppose when you leave the mechanic with your car in top shape – but it’s not a metaphor that feels right.

    There’s plenty of other aspects that don’t overlap between cars and websites. Website hacking, car insurance, and your friend borrowing your car – it doesn’t all match up. 

    Finishing The Trilogy

    I hope this article and the others in the series help to provide you with better context in your next web site or application project. To wrap up the series I’m going to dive more into the experience of working with a partner when building a website. 

    How Building a Custom Website Is (and Isn’t) like… A Fine Dining Experience (3 of 3 in Series).

  • Building a Website is like Building a House: An Analogy to Help Custom Web Development Make Sense

    Building a Website is like Building a House: An Analogy to Help Custom Web Development Make Sense

    We use many metaphors (or analogies) when trying to describe what goes into custom web development. Building a website or web application is technical, complex, and sometimes tricky. Metaphors like “building a house” are helpful in aligning expectations from sales to deployment to ongoing maintenance – but they’re never perfect.

    This series will cover some of the main metaphors we use, both internally and with clients. I’ll describe some of the major and minor points that correlate – but also some of the nuances that aren’t the same. You can always jump to the other articles in the series, which compares website maintenance with owning a vehicle and the experience with a development agency to fine dining.

    We’re Talking About Building a House, Not Buying 

    Building a house is probably the most common analogy used when describing what we do. And we don’t mean buying a house that already exists; we mean building one from scratch. Imagine all the planning and decisions which you (as the eventual homeowner) would need to provide to others so you one day take out your shiny key, unlock the front door, and step into your perfect living space.

    We heavily leverage the five phases of software development with custom web development, and I’m mostly going to reference the discovery, design, and development phases.

    Discovery, or Why Do You Even Want a House?

    You may have already thought about blueprints as part of the analogy of building a house. Let me stop you though – we’ll get there soon.

    This is the house you want, you’ve always dreamed of, made for you – you’re not picking from a few pre-existing models. How would you feel if you hired a builder, and a week later they brought you blueprints only knowing you want four bedrooms? Wouldn’t you expect to spend some time explaining as many details as you can? Wouldn’t you expect the builder to ask you questions you didn’t know you needed to answer?

    This is discovery. We (as the builder in this scenario) want to know as much as we can because we want you to be thrilled with your dream home (er, website) and be proud that we built it. We want to make informed choices as we move into design.

    In the sales process, you’ve told us roughly how many rooms, a square footage range, desired location, and budget. That’s great, but how do you want to use your house? Do you have a family, and if so, how big is it? Do you want to entertain? Maybe you and your partner have differing wants and goals. These are analogous to the questions we ask during Stakeholder Interviews. We want to know from the people who are most vested in the project what would mean success to them.

    Let’s talk about your current house. What do you like, what don’t you like? We might use public records or have a house inspector visit to provide us more detail. This correlates to our Technical Audit, where we can review your current website, crawl public web pages, and/or have a developer or architect meet with you. You might invite us to walk through your house room by room, show us where you spend most of your time, and describe what you like and don’t like. This correlates to our Contextual Interview, where we can utilize screen sharing to watch a user use the website and ask questions throughout.

    As we start understanding your goals, likes, and dislikes, we’re going to start defining a list of home features. This may grow and change as we continue to plan and build, but our designer and our architect will need this list to eventually determine all the details for your website. This is our Requirements Matrix. It’s not deep in details, but should cover the main points of the custom web development. For example, this list may indicate you want a two car garage but doesn’t indicate details like dimensions or flooring materials.

    Design – or Unveiling the Blueprints

    You’re ready to stop talking about your new house – you want to see something! This planning period, design, has the most obvious overlap between home building and custom web development. Hell, we share role names like designer and architect, and that’s not just coincidence. What may surprise you is what those two roles perform in these scenarios don’t match up exactly between home and website building.

    You’ve seen it in film and tv plenty of times. An architect pulls a giant roll of paper from a large case of them. She rolls out a blue and white graphic that’s a few feet across in both width and height. But this time? It’s your house – the open living room with a few columns, a master bathroom with multiple windows to let in light. There are details of specific widths and general drawings for stairs, counters, and toilets. We commonly correlate this to our Wireframes. There’s no color, no ambiance – but you can now start to picture the result and you’re getting something tangible from the builder. But in our case, it’s not the architect that made these – it’s the UI designer.

    What else does the designer do? The main thing you’d expect – the visual representation of your final home. The mockups. An artist’s rendering of what a photo will pretty much look like when it’s built.

    But wait, what about the architect? Remember when she pulled the blueprint from a case? She has a number of other large documents that you might not ever see.

    There are designs on the foundation of the house. This includes the physical foundation but also information on the land and details of the physical material expected in the build. This is akin to our Architecture Diagram, which spells out what hosting platform and services that will be used. It is commonly created by IT engineers conferring with an application architect or senior developer.

    There are designs of all the pipes, wires, and anything that spans your property edges to the city or other properties. This analogy gets a little more vague, but might be attributed to any Integration Specifications if the website needs to communicate with other cloud services.

    A Few Analogies in Custom Web Development

    Once ground is broken and building begins on your house, there’s a lot of waiting. This is, unfortunately, very common in the custom web development space as well. You’ll be in contact with your project manager (same role name for us), and you might get occasional questions from our foreman (lead developer). We’re also orchestrating with the building crew (web development team), inspectors (quality assurance, or QA), and any others who will be necessary to successfully complete your project.

    We could dive even deeper in the metaphor – how architecting and writing the code can mimic physical house structure… but that’s a wholly different article!

    But not everything about building a house matches custom web development!

    There’s a huge assumption being made when we correlate custom web development and building a house. That assumption is: you want to plan, estimate, build, and buy a completed house. In software development, that’s not the only path you can take.

    You can use Agile Development as a methodology, which (very, very roughly) means building small pieces of your website at a time. It’s not like building one room of your house, then you move in, and then you build more rooms one at a time. That’s close, but it’s more like planning, designing, and constructing your kitchen counter, then doing the same for your cabinets, and floor; eventually, you’ll have a whole room and can keep going on the next. It honestly doesn’t fit the home building analogy at all.

    Sign-offs, Implicit Acceptance, and Changing Requirements

    In all phases of custom web development, we want and need your feedback! The last thing we want is for you to show up at your new house and have it look like we planned, but deep down you don’t like it… We ask for feedback, sometimes actual sign-offs, at points in the process such as at the end of a phase. There’s also “implicit acceptance” which means if we’ve been positively working with you through the planning and never received formal acceptance or rejection, we’ll continue to make progress as if it’s accepted. This is to protect all of us.

    The foreman brings you on site to see the house halfway through the building process. You walk into the half-kitchen, and… oof. You saw the plans for the island, but now that you see it in person? It’s… not what you hoped. Is it your fault? Nope. Did the designer or builder do anything wrong? Nope. Can it be changed? Yes, but we don’t know how easily.

    This is a great same-but-different scenario with software development. Change is inevitable, so it’s fine – just know changing plans in the middle of the initial build might be tricky! If you’ve watched any HGTV shows, you may have seen that an update may need a new design or might be changed on the fly. There’s just a cost of time, and sometimes dollars.

    Next Up

    I hope this article, and the others in the series, help to provide you with better context in your next custom web development or web application project. However, website projects don’t end at launch. Next in the series will be more focused on the owning / maintenance of your site.

     How Building a Custom Website Is (and Isn’t) like… Owning a Car

  • Deploying a .NET Core API to AWS Lambda & API Gateway using Bitbucket

    Deploying a .NET Core API to AWS Lambda & API Gateway using Bitbucket

    After a transition to Bitbucket for our repository hosting last year, we’ve been setting up more and more CI/CD using Bitbucket Pipelines. I recently converted a .NET Core API project that was deploying to an auto-scaling group of EC2s into a project that could be deployed in AWS Lambda behind API Gateway using Bitbucket. The web project that consumes this API is written in Angular.

    As a shop that leverages automated deployments in multiple environments, I found documentation on the web to be in short supply other than very basic “deploy using VS Studio” articles.

    As part of updating the API project to Lambda, I did make my LambdaEntryPoint reference APIGatewayHttpApiV2ProxyFunction and the serverless template event of type HttpApi. A guide to these updates can found here: One Month Update to .NET Core 3.1 Lambda

    In this post, I provide some snippets of YAML code which I found out in the world that didn’t work, and also what ultimately did.

    Jump to What Worked

    What Didn’t Work

    aws-sam-deploy

    caches:
  - dotnetcore
steps:
  - export PROJECT_NAME=this-dotnet-project
  - dotnet restore
  - dotnet build $PROJECT_NAME
  - pipe: atlassian/aws-sam-deploy:1.5.0

    When trying to use the aws-sam-deploy pipe, I wasn’t able to leverage enough options or get the API to run the .NET code successfully. The API Gateway endpoint was running and hitting Lambda, but I was getting system errors I just couldn’t resolve.

    Using project appsettings files

    Since appsettings.json files contains secrets, we don’t check them into the repo. At some point I was receiving these errors, and I realized that the appsettings files weren’t getting deployed correctly. 

    run_dotnet(dotnet_path, &args) failed

Could not find the required 'this-dotnet-project.deps.json'. This file should be present at the root of the deployment package.: LambdaException

    We ended up injecting the appsettings content using the AWS Parameter Store with aws ssm get-parameter.

    dotnet publish, zip, and aws-lambda-deploy

    - apt-get update && apt-get install --yes zip
- dotnet restore
- dotnet publish ${API_PROJECT_NAME} --output "./publish"  --framework "netcoreapp3.1" /p:GenerateRuntimeConfigurationFiles=true --runtime linux-x64 --self-contained false
- curl -o /bin/jp -L https://github.com/jmespath/jp/releases/download/0.1.3/jp-linux-amd64 && chmod a+x /bin/jp
- aws ssm get-parameter --name "/this-project/api/dev/appsettings" --with-decryption --region us-east-1 | /bin/jp -u "Parameter.Value" | base64 -d > ./publish/appsettings.json
- zip -r -j package.zip publish/*         
- pipe: atlassian/aws-lambda-deploy:1.5.0
  variables:
     AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
     AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
     AWS_DEFAULT_REGION: ${AWS_REGION}
     FUNCTION_NAME: "this-dotnet-project-AspNetCoreFunction-LZj5pbvV0GRT"
     COMMAND: "update"
     ZIP_FILE: "$BITBUCKET_CLONE_DIR/package.zip"

    We have some single Lambda functions (not behind API Gateway) that use this method for deploying. It works great. I tried using this method pushing to a function that was built with a stack published via VS Studio. No luck. It’s possible there was a problem with the stack that was built, but I think this package wasn’t exactly right.

    What Works

    The following is the pipeline for a single branch, our develop branch. I haven’t yet refactored using template steps, but this is easier to read through for this article anyway.

    I have scrubbed the contents of this YAML, but the repo contains:

    • Root (.sln file)
      • .Net Core API project directory (named this-dotnet-project here)
      • Angular web project directory (named this-web-project here)
    pipelines:  
  branches:
    develop:
      - step:
          name: API (.Net Core) Build & Deploy 
          image: mcr.microsoft.com/dotnet/core/sdk:3.1
          deployment: Develop
          script:
          - apt-get update && apt-get install -y zip && apt-get install -y awscli
          - dotnet tool install -g Amazon.Lambda.Tools
          - export PATH="$PATH:/root/.dotnet/tools"
          - curl -o /bin/jp -L https://github.com/jmespath/jp/releases/download/0.1.3/jp-linux-amd64 && chmod a+x /bin/jp
          - aws ssm get-parameter --name "/this-project/api/dev/appsettings" --with-decryption --region us-east-1 | /bin/jp -u "Parameter.Value" | base64 -d > ./this-dotnet-project/appsettings.json
          - cd this-dotnet-project/
          - dotnet lambda deploy-serverless --aws-access-key-id ${AWS_ACCESS_KEY_ID} --aws-secret-key ${AWS_SECRET_ACCESS_KEY} --region ${AWS_REGION} --configuration "Development" --framework "netcoreapp3.1" --runtime linux-x64 --s3-bucket $API_S3_BUCKET --stack-name $API_STACK_NAME --stack-wait true
      - step:
          name: Web (Angular) Build
          image: atlassian/default-image:2
          caches:
          - node
          script:
	      - cd this-web-project #The angular project is currently in a subfolder in the same repo
          - nvm install 12
          - nvm use 12
          - npm install @angular/cli
          - npm run build:dev
          artifacts: # defining the artifacts to be passed to each future step.
          - dist/**
      - step:
          name: Web (Angular) Deploy
          script:
          - pipe: atlassian/aws-s3-deploy:0.5.0
            variables:
              AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID} 
              AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
              AWS_DEFAULT_REGION: ${AWS_REGION}
              S3_BUCKET: ${WEB_S3_BUCKET_DEV}
              LOCAL_PATH: "this-web-project/dist/this-project-output-path/"

    apt-get install and dotnet tool install

    Items that were quickly apparent as missing before adding them, more of a “duh” leaving them out when trying so many things.

    dotnet lambda deploy-serverless

    This was the big command that mostly got things working. I finally found this is effectively what’s happening when you deploy the API project from VS Studio.

    –stack-wait true

    In Bitbucket, without this, the build shows as successful when the stack build is kicked off. By adding this flag, bitbucket will wait for the full build or update before continuing.