Forem: Elisabeth at Praxent

10 Tips for Seamless Software Hand-offs & Technical Documentation

Elisabeth at Praxent — Thu, 21 Nov 2019 22:45:59 +0000

Technical documentation is a set of instructions and information intended to equip other developers with the context they need to understand custom-written code.

When handing off custom software to other developers, clear and thorough documentation is essential. It can also be complex, so the best way to develop documentation is to keep organized notes throughout development. When it’s time to hand off a set of code, all you’ll need to do is revisit and update your notes, then compile them into a set of instructions that any developer can understand.

Never underestimate the importance of documentation. Developers who provide professional and thorough documentation will save themselves and others future headaches that can otherwise result from double-working or unnecessary mistakes.

Here are 10 tips from subject-matter expert, Rico Callirgos, for creating technical handover documentation and smoothly transferring custom code:

1. Plan ahead to hand off code.
Give yourself a month to fully transfer custom code. Spend the first two weeks of that month writing documentation and training the new developers. Spend the last two weeks in a support role, answering questions that come up as the new developers work with the code.

2. Include a high-level view of the software architecture.
Provide a document with a high-level view of the application. This software architecture overview should illustrate how the different elements and functions of the application work together.

>> Work with .NET, Python, Ruby on Rails, Java and CMS development technologies.

3. Provide a database schema.
A high-level view of the database schema shows other developers how various types of information relate to each other within the database. It helps them understand how the data is supposed to be interpreted and what the goals of the system are.

4. Provide step-by-step instructions for completing manual processes.
Some software functions require occasional manual intervention, like pulling reports. Create an exhaustive list of these tasks, then include step-by-step instructions on how to complete each one.

5. Equip other developers to troubleshoot and resolve common bugs that have already been identified.
Make a list of all bugs that have been encountered to date with the software. Include this list in your hand off materials, along with instructions for resolving and troubleshooting these bugs should they resurface with the new developers.

6. Explain how to push new releases.
Write out simple instructions with clear steps for pushing out new releases of the code. This portion of documentation needs to be very straightforward and actionable to save new developers from making costly mistakes.

7. Capture miscellaneous historical details about the code in a “Deprecated” folder.
Details about why you made certain decisions or what kinds of factors were involved at each point of development can be extremely valuable to developers who are new to your code. Historical documentation will save them the trouble of re-inventing the wheel and will equip them with the insight they need to solve problems effectively.

8. Include notes about your source code.
It can be really helpful to include notes highlighting various important sections of your source code. When working with thousands of lines of code, source code sections can help other developers easily find critical pieces.

9. Implement version control procedures.
Once testing is complete and your code is ready for others to work with, you’ll want to commit it to version control. Version control ensures finished code will remain secure and unaffected by future software changes.

Be sure to also follow all additional version control procedures for securing your code for future use.

>> Learn about product version control, RESTful version API URLs, and other version control best practices.

10. Write coding standards.
Good custom code developers always set and follow rules and standards for writing their code. These rules provide continuity to the code, allowing others to understand and work with it easily. Equip other developers to understand and preserve these standards with a list of each rule and examples illustrating how to follow it.

Cover Photo by Kevin Ku from Pexels Photo

Why Immer.js Is an Excellent Choice for Reinforcing Immutability in React

Elisabeth at Praxent — Tue, 24 Sep 2019 23:30:51 +0000

Unless you're already an expert in immutable.js, consider working with immer.js instead. It has a simpler API, and, unlike immutable.js which does not easily interoperate with JavaScript, immer.js allows developers to work fairly easily with native JavaScript constructs.

What is Immer.js and Immutability?

Immer.js is an increasingly popular tool for reinforcing immutable data structures in React. Immutability refers to an unchangeable, unalterable state. It's important to ensure that immutability is properly enforced, even when using Redux.

That's because it is possible to mutate the Redux store, resulting in bugs and issues. Immutability libraries like immer.js and immutable.js exist to provide an extra layer of strength behind already stable Redux containers. This ensures beyond a doubt that states accurately update, protecting against otherwise possible mutations.

Top 3 Benefits of Using Immer.js

On a recent web application development project at Praxent, an Austin-based Inc. 5000 company, software developer Peter Elbaum evaluated the risks and made the informed decision to use immer.js instead of the default, immutable.js.

When asked what drew him to immer.js over immutable.js, he offered two main reasons:

1. Simpler API
Immer’s API is easy-to-use. Peter only had to review the documentation a few times to grasp the core concepts. This stands in stark contrast to the steep learning curve involved in mastering immutable.js.

2. Interoperable with Native JavaScript
Immutable.js involves working with data types that are not native to JavaScript. To use it effectively, developers have to spend hours learning a new data type that is otherwise irrelevant. With an alternative like Immer, it just doesn't make sense to dedicate the time and brain power to learning immutable.js.

Immer.js, on the other hand, is fairly easier to learn. It solves the same problems as immutable.js, but in a more streamlined and efficient manner.

3. Great for Writing Redux Reducers & Tests
Immer.js syntax provides a clear expression of outputs and inputs, which means developers can avoid most object creation and destructuring.

The Downside: Immer.js Does not Support JavaScript Classes

While immer.js is the clear winner over immutable.js, it does have one disadvantage: it does not support JavaScript classes.

To make immer.js work with JavaScript classes, developers need to enable class copies by adding a special flag. As a result, constructor is lost, causing classes to behave like normal objects.

Unfortunately, this caused state mutation and bugs in Peter's project that were difficult to diagnose. This was partly due to compatibility issues with Praxent's React boilerplate, which uses OOP to model database resources.

Immer.js documentation is clear about the lack of support for JavaScript classes, claiming that class support would conflict with the architecture behind the immutable state tree. Be prepared and plan for this ahead of time.

Positive Results with Immer.js

When put to the test, immer.js proves to be a solid option for reinforcing immutability in React. It removes the need for complicated string paths, offering a simple, streamlined alternative to immutable.js.

>> Master version control on enterprise apps. Access our white paper for an in-depth look at version control beyond Git, and learn more about custom software development at Praxent.

5 Experience Design Takeaways for Developers

Elisabeth at Praxent — Thu, 18 Jul 2019 20:47:36 +0000

Experience design places users and business drivers at the helm of product strategy and development. With experience design, authentic innovation is possible. Without collaboration across design and development, however, misalignment cripples the most well-intentioned experience-design process.

As a developer, how much are you willing to collaborate for the sake of innovation? Proactive developers can help drive authentic innovation by contributing to and learning from the experience-design process.

Here are 5 ways you can partner with design and business stakeholders to produce truly innovative digital products.

1. Allow product vision to define your work.

The best developers lay aside personal vision for the app or other digital product they're working on. They instead work with business stakeholders and designers to understand and adopt product vision that drives user- and-business--centric outcomes.

When vision is driven by technical priorities, you can create technically flashy products that excite other developers--but you won't be able to create innovative products that change the way people live and work.

Developers who adopt big vision can steer their teams away from rabbit trails and help them make decisions that lead to business success.

2. Understand business and user goals.

Successful digital products generate financial return by improving the right user experiences. Work with designers and business stakeholders to understand where business goals and user goals intersect--that's the product purpose.

Ask for a simple explanation of product market fit for the app you're working on. Request access to journey maps, user personas and mental model diagrams to understand who will be using the product and why.

Then, use your technical expertise to deliver on that purpose with the highest functioning code at the lowest cost. You'll make money, your client will make money and your product will change the way the world works.

3. Collaborate on user stories.

Good user stories create alignment around product vision and smooth the transition from design to development. They accurately represent business and user goals in a way that's helpful and clear for developers.

When written in isolation, user stories can lead to confusion and gaps. Make sure designers, developers and business stakeholders are all offering input. In some cases, you'll need to provide coaching on how to write user stories in a way that effectively communicates what developers need to know.

>> Learn how to write user stories with Gherkin syntax. Access the free template and step-by-step guide.

4. Align decision-making parameters with product vision.

Once you understand product vision and how your work will serve to further user and business goals, you'll need a way to keep development in line with project priorities.

At this stage, it helps to create a list of decision-making parameters. These parameters serve as standards or rules that developers can turn to when making decisions about how to move forward with developing a feature.

Should you prioritize readability over speed? Or accessibility over aesthetic? Creating a clear list of project priorities will go a long way to make sure development decisions line up with product vision.

5. Join discussions about product concept.

Learn from designers and business stakeholders and allow them to learn from you by joining product concept discussions.

Not only will you pick up on the purpose and background of a product by participating in early visionary talks, you'll also be able to contribute critical technical input that should shape product direction. Designers and business stakeholders who care about product vision will welcome your advice on technological opportunities and constraints.

Collaborating at this level will lessen confusion later on in a project and smooth the way for faster, more targeted development.

>> Check out the infographic and article series on how developers, designers and businesses work together.

Why We Built a Custom React Boilerplate (Hint: Collaboration & Speed)

Elisabeth at Praxent — Thu, 01 Nov 2018 19:50:17 +0000

Creating a custom-built React boilerplate can speed up initial development and help teams of developers collaborate more efficiently. While it required more time up-front to build the boilerplate, it's saving our teams tons of time in the long run.

This case study powerfully demonstrates the importance of laying a common foundation for collaborative coding.

Keep reading to learn how they built the boilerplate and what we've seen as a result of using this new tool.

A Custom React Boilerplate that Reduces Initial Sprints from 2 Weeks to 3 Days

Ryan Ostrom and Eddie Rozum, two all-star developers at Praxent, put their heads together to create a boilerplate for use by all teams and developers working on React projects within our organization. The custom-built boilerplate accomplishes the following goals:

Reduce the amount of time spent setting up a build process at the beginning of each project. What used to be a 2-week initial sprint is now usually only a 3-day set-up process, at the most.
Provide every developer with exactly what they need to know for testing. The boilerplate equips developers with information about what to test and how to write each test. Less experienced developers can now write tests without relying on busy experts from other teams. The boilerplate documentation has examples for each type of test that needs to be written, plus a holder structure built in. It automatically includes Jest in the test script.
Enforce best practices for new web apps.
Limit errors, facilitating faster coding.
Make outcomes more predictable. (We know input and output values ahead of time.)
Re-enforce data integrity for stronger security.

What's Inside the React Boilerplate

The boilerplate presents developers with a production development build script; a local, live development server and pre-arranged folder structures.

Developers no longer have to create a build process from scratch. Instead, when beginning a new React project, they simply make a few adjustments before they’re ready to start developing.

Here are the customizations each developer has to make to the build process once they've accessed the boilerplate:

Customize parameters for the project
Add the boilerplate to source control
Hook up the CI/CD pipeline for continuous integration and deployment

Better Collaboration

Eddie and Ryan created this tool to facilitate better collaboration among multiple developers working on different projects within our organization.

They wanted to create a tool that would allow any new developer added to a React project to quickly catch on and make it easier for senior developers to understand the layout of a project when reviewing code.

The opinionated boilerplate includes built-in structure for implementing automated testing. It has automatic code splitting built into the tool. (Code splitting allows developers to access only the JavaScript they need at any given moment, rather than pulling chunks of related JavaScript which they must manually sift and separate.)

Here is the technology stack used for this React boilerplate:

React.js: JavaScript library for building the interface
Redux: Library for managing the React application global state
Immutable JS: Immutable collections for JavaScript
Webpack: Module bundler for budnling SCSS and JS files
Create-React-App: Ryan and Eddie started with the React boilerplate called create-react-app for their customized tool

Learn more about the custom React boilerplate created by Eddie Rozum and Ryan Ostrom: "How to Speed up Development on React Projects | React Boilerplate"

10 Ways to Become a Better Developer

Elisabeth at Praxent — Thu, 29 Mar 2018 20:12:26 +0000

1. Find & Embrace "Team"

Teams are crucial to implementing almost every point made in this article. When we say “team,” we mean a group of knowledgeable programmers who work toward the common goal of making each other’s code the very best it can be for its given purpose.

If you’re a freelance programmer, find community that can serve as a stand-in team. It’s amazing that, at places like DEV, you can find people who will critique your ideas and code as though they had a stake in its success. Don’t take these people or their comments for granted; rather, find ways to thank them!

If you’re already on a team, dive into your role with zeal. On the Software Engineering Stack Exchange site, there are 14,827 questions related to working on teams. If teams weren’t crucial for innovation, quality, and progress, people wouldn’t put up with them!

Reflect frequently on your appreciation for your team and the mutual dependence you share. This will enable you to see past the interpersonal challenges that come with being linked to other programmers equally staked to the success of your projects.

2. Learn to Say “No” the Right Way

Nobody develops successful, purposeful code in a silo. For better or for worse, programming almost always comes with people, purpose and disagreement. As a craftsperson with expertise and an eye for quality, you may find yourself in situations where saying “no” to people is really needed. But pushing back without burning bridges doesn’t always come easy.

Perhaps your manager has unwittingly made a request that will set back the project. Or maybe your client is asking you to execute a terrible idea you know will never work. Whether it’s with your client or your boss, saying “no” can be risky. But if you handle the disagreement well and learn to stand strong on your expertise, it can help strengthen relationships and build confidence in your abilities.

Here are some practical tips for communicating in these touchy situations:

Provide recommendations and alternatives using positive language.
Once the other party concedes, follow up with clear, direct language, confirming your mutual decision. This way, you can move forward decisively and confidently without having to worry about: “Hey, I thought we were doing [XYZ]!” Leave no room for misinterpretation.
Identify and acknowledge together your common goals.
Talk through the “how” of reaching those common goals, and come to an agreement.
You’re on the same team. Show your investment in the success of the project by being rational at all times and supporting the other party, even if they don’t change their mind.

Here are some helpful phrases for disarming the person you’re talking with and opening the way for vulnerable, productive communication:

“It sounds like what you’re saying is…”
“I may be wrong…”
“I’m probably completely off the mark here…”
“Would you mind if I share my perspective?”
“Feel free to step on my toes here…”

(These tips are courtesy of Ryan Ostrom, software architect at Praxent. Read more of his thoughts on positive disagreement at work.)

3. Get Your Code Reviewed

Chances are, your code has a job to do beyond just being written. There are tasks and objectives it is expected to achieve. And if this is a paid project, your code must come through on its promises. So there’s no question--code reviews are essential, especially if the project involves languages or scenarios that are new to you.

Successful code reviews are positive and constructive. Don’t just go through the motions to say you did it. If you’re passionate about programming and take pride in your work, it will show in the way you receive and implement others’ feedback.

4. Review Code for Others

Great developers learn how to make the most of code reviews from both the receiving end and the giving end. There is certainly a lot to learn from having your code reviewed, but there’s also a lot to learn from reviewing someone else’s code, yourself. After all, you don’t really know something until you teach it.

Code reviews can go a long way in strengthening teams. They help cross-pollinate knowledge and insight around the team, allowing teams to lift each other up to the same level. They provide a platform and opportunity for aligning on standards and techniques.

When reviewing code for others on your team, start from a position of appreciation. Recognize that what’s good for the team is good for you. It’s in your best interest to lift up the developers around you through constructive feedback that not only makes their code better but instills them with confidence and equips them to confidently course correct. Never demoralize another developer.

5. Code Accessibly

The best developers think outside the box of their own computer. Your code might work here, now, on your screen. But you’ve got to think about where else your code may be headed, and will it still work when it gets there?

What if it changes hands? Your code must be readable. This means others can read and understand variable and function names within the general structure of the code. Any developer should be able to read and understand what the code is supposed to be doing.

This is easier said than done. Most developers naturally have a unique style. Some take pride in being different in the way they write their code. There’s nothing inherently wrong with creating new and different ways of writing code. But if you want this code to accomplish anything beyond the limits of what simply looks cool today on your screen alone, then save the creativity for better use. Write code that others can work with and understand, and that won’t leave you scratching your chin several months from now, trying to remember what you meant by:

for (int m = 0; m < 34; m++) {
    i += (s[m] * 4) / 5;
}

6. Code for the Future

For similar reasons that your code should be readable, it should also be maintainable. How easy will it be for you or someone else to alter the code in the future?

If there is a structural change you can make today that will save hours of labor in the future, do it.

7. Don’t Be Naive, Security Matters

The Identity Theft Resource Center reported 1,120 total security breaches and more than 171 million records exposed in the US in 2017.

Code as though the application will be processing your own social security number. If there’s even a chance that the project you’re working on could involve the exchange of any sort of confidential information, code must be written with security in mind at every stage. Being mindful about the potential impact your work could have on others is what sets apart responsible coders from the rest.

8. Use Coding Standards

If you or your team doesn’t have coding standards, create them (preferably together). Create them even if you’re a freelance programmer. Once you have standards, it’s even more crucial that you stick with them.

Why do coding standards matter? It all comes back to promoting longevity and multi-purposeness in your code. For example, if inconsistent formatting makes its way into the final product, it could result in unexpected breakage. Adhering to coding standards ensures consistency, saving time in the long run by revealing potential bugs before it’s too late.

You may not feel the need for coding standards until you’re working on a big project with lots of moving parts and multiple programmers. But it’s never too early to start instilling that DNA into your work, even if you’re a solo programmer. The code you’re working on now may be needed again further on down the road when coding standards really matter.

9. At the End of the Day, It Has to Work

Your code doesn’t just have to work, it has to work for the end user. And it has to work in every context for which it’s purposed. For this, testing is crucial.

What happens when the user inputs an unexpected digit that your code was not built to handle? Does the application recover gracefully? Or crash the whole network?

UX design and prototyping are increasingly essential for creating digital products that succeed today. Just because you're not a UX designer doesn't mean you aren't developing for the user. In fact, the best code is developed AFTER the user interface design has already been touched on.

If you're working on all stages of your project, from design through code, remember that you don't have to be a huge software company to conduct usability tests. Keep it simple, but make sure it's covered in your process.

10. Code for Fun

In business, there’s no such thing as technology for technology’s sake. But as a programmer, there is definitely a time and a place where coding should simply be about geeking out on tricks and experiments. Your gift of programming is not just for helping others get things done, it’s for your own enjoyment as well!

Participating in hackathons or developing side projects can be a really healthy outlet for developers to simply exercise their skills without pressure or constraint.