DEV Community: Kat Chuang

Getting Started in Software Development Guide: Moving from Idea to Product

Kat Chuang — Mon, 20 Sep 2021 02:01:32 +0000

This is an introduction to software development tools, techniques, and processes. I wrote this up last year for a class to give a roadmap to the undergraduate CIS students as part of my larger collection of writings, Getting Started Guides that aims to prepare them with practical skills used in industry. If you like this kind of content, I've love to know. Give it a ♥, follow me, and comment to let me know!

This guide is written in three parts.

Part 1 - Planning

The planning phase is where you divide the main goal into smaller, specific goals.

A common model for presenting the phases of planning for and building software goes by the name of Software Development Life Cycle (SDLC). These are typical chunks of focused activities with any software project, each phase has its own set of processes, tools, and expectations. A typical project moves through the phases in the order listed in the table; to transform a rough idea into a specific plan, to the finished product. One might potentially cycle through these phases repeatedly depending on feedback throughout the whole project.

Phase		Tasks	Deliverables
Planning	Requirements Gathering It helps to know what you’re building before you begin building. Deciding what to build comes from information gathered through discussions with all the stakeholders involved.	User Research, Market Research	User Stories Spec List
	Design / Specifications The general requirements scoped needs to be translated to technical specifications such as defining what done looks like, and picking appropriate tools to complete the work.	System Design	Data flow diagram Flow Charts System Diagram Wireframes Mockups
	Scheduling With the target(s) in mind, you need to figure out when to complete each feature and in what order. It helps to make shorter term mini sub-goals, such as weekly targets.	Estimations	Gantt Chart Project Proposal
			Project Proposal
Implementation	Building This is the execution of your schedule. Check in with your sub-goal targets to ensure you’re on schedule.	Coding Unit Tests Version Control	Source Code DB Schema Design Assets
Implementation	Testing Test your application against the initial requirements.	Testing	Testing report
Delivery	Delivery/Deployment This is the final stage of the project, when you’re ready to deliver the project. For a website it can mean deploying the website to the server.		Source Code Documentation User Guide

Each of these phases are described in more detail in the next section, SDLC Phases, in the next main section.

Part 2 - Defining areas of responsibility on a software team

A sampling of possible roles or teams on a project. This might be how you would generally break down areas of concern for a larger team web project. Or, if you’re working solo how you might allocate time to focused streams of work.

Role	General Responsibilities	Examples of Deliverables
Product	Design the app based on market research Figure out user needs Deciding on features for the end user what it will look like	User stories or use cases Wireframes and other mockup documents Style guides that show look and feel
Database	Compare possible database implementation solutions Create and edit table(s) Maintain tables Curate content, create tables and maintain them Backup plan(s) - How do you ensure data isn’t lost? Security plan for data - how do you secure data and work with backend team to decide on access/permissions	Table schema(s) Creation statement code (any queries) Data flow diagram Write up comparing database options and rationale for selected DB product
Front-End / GUI	Implement designs Discuss with product the feasibility and prioritization of features Works with backend team in delivering new features	Front end code including template and static files Writeup of templating decisions i.e. do you want to separate out header to its own file? Write up the rationale for selecting the front end stack. Are you using frameworks, etc?
Back-End	Work with front end and database to architect the app Build data flows for transforming data, (i.e restful api) and transformations for access by the frontend	Back end code including models to connect to database schema Writeup of architectural decisions like how’d you decide on route handling? System architecture diagram
Quality Control	Develop a testing strategy. Could be both manual and automated testing strategies Convert requirements and design documents to a set of testing cases and scripts	Test plan with an overview of test cases Reports of tests performed and their performance Define app parameters or configurations for regular tests versus edge case tests. Define scope of tests - i.e. are you testing mobile and/or desktop?

Part 3 - Software Development Life Cycle (SDLC) Phases

There are specific chunks of focused activities and sample deliverables for each type of activity. Some teams might go through each of these phases slowly once through the cycle (i.e. Waterfall model), or go through shorter bursts of work of the entire cycle repeatedly (i.e. Agile). Some teams might even take a rapid pace through the phases in the matter of days or weeks to reach a proof of concept prototype before cycling back to progress again for a more thorough attempt. Other times, a project such as a distributed system of many components, requires conducting a cycle through feature development of one component before moving on to the next.

Requirements Gathering

The purpose of this phase is to gather relevant and useful information.

There are many avenues to gather information. You can compare with similar projects to see what features they exhibit, which is a form of competitive analysis. When you host focused conversations to gather information you can select end users who will be using the software, which is called user research. Or you can speak with other stakeholders such as the people interested in sponsoring the project for their wishlist of features. The resulting list is the requirements for the project.
When describing this list of features, it helps to be as specific as possible. Some teams use a type of description called user stories to highlight possible use case scenarios. The focus of the descriptions tends to be external facing, that is the non-technical uses.

Design / Specifications

The purpose of this phase is to convert the user stories into well-defined, specific building blocks of the eventual architecture.

This may be presented as a textual description that describes data transformations from raw data source to its final form and any tools used to make that happen. This kind of information may also be presented graphically and with high level or abstract manners as a flowchart or a data flow diagram. Eventually details in the high level diagram are decided and they flesh out to create a detailed diagram showing the architecture of the software. Examples of these architectural diagrams are available at The System Design Primer by Donne Martin.

The user interface (UI) might also be sketched out. You can have high level wireframes that give a sense of a general layout, storyboards that show how the end user would move through pages. During this phase some teams might create a mockup, which is a sample prototype to trial ideas to help with decision making of various options for implementation. You can create a low fidelity (i.e. pencil and paper sketch) or a high fidelity (i.e. html+css) version, or both versions depending on time available.

For example, the building block could be building a login feature to a website. A database would need to be selected for where user information is stored, to compare against user input. The user input fields on a UI would have to be defined. Further, the connecting mechanism between the UI and database would have to be defined.
One the building blocks are defined, you are ready to schedule the work.

Scheduling

The purpose of this phase is to be able to define when to complete the work as well as who will complete the work. In effect, this turns a specific plan into a plan of action.

It is easier to schedule well defined blocks that come from the design/specification phase.The nature of software projects, of doing something new for the first time, is such that figuring out an appropriate schedule can require shifting between this phase and the previous several times to arrive at a specific plan of action that defines who will work on what, and when each task will start and complete.

For example, the building block of building a login feature to a website. The tasks might include installing a database (i.e. PostGres) and creating the database schema; then connecting a web framework to connect to the database to allow retrieving information. The decisions being made in the scheduling phase is to decide who will be working on each task, the time allotted to each task, and the order in which it will be completed.
One might set specific targets or milestones, to indicate a checkpoint.

Building

The purpose of this phase is to complete the items specified in the plan (often, such a plan appears in a project proposal that specifies the work to be done before the work begins). If the specifications for the end product are well defined, it becomes a straightforward process to build the software without much delays and obstacles. When the schedule is well defined, at the time of the check-point it becomes clear what should have been done by that point.

Some teams use project management software (i.e. a kanban board or Jira) to track the work that needs to be done. All software teams should be using a version control system (VCS) to track changes in their source code. Git is very common these days, but it isn't the only choice out there.

Testing

The purpose of this phase is to ensure that your product is of high quality by using various deliberate scenarios. It would mean for example that it operates as expected for certain inputs. For example if it’s a calculator then the rules of addition should follow mathematical principles. Or perhaps you are working on a website and you want it to look polished to the end user on both desktop and mobile, so you would want to preview on both types of devices.

Another reason for coming up with a test plan beyond measuring the build quality is to have in writing some form of explicitly defined limits to the end of your work, particularly if you’re working on an open ended project that doesn’t have a clear finishing point. By defining test cases that align with the requirements, it becomes easier to identify when you are done with the project. It becomes easier to measure whether you’ve completed the work you set out to do.

Delivery / Deployment

The purpose of this phase is to ensure that the product can get into the hands of the intended end user.

If this is an application that will see new releases while in production, then a continuous integration (CI) process would be good to have in order to think about how to release updates. Sometimes the continuous integration is paired with an automated testing plan.

Many times a complete product comes with documentation to explain the work that was done, the specifications of the program (such as inputs, configuration settings, and outputs) and features included. Source code is often provided as well as an executable (if it’s a desktop application), or a deployed version (if it’s a web application).

Ramblings on reading skills

Kat Chuang — Sat, 26 Sep 2020 01:03:55 +0000

Over the past year I've had a number of conversations with both industry and academic folks about the importance of reading for future college graduates. Reading is very important for discerning key information related to job postings, but also in the course of completing everyday activities, such as following instructions.

Reading is a huge part of a developer's career. Some areas where reading is very important:

Reading to learn new technologies (new frameworks, new releases, new languages, etc)
Reading to understand the spec requirements
Reading the error message(s)
Reading a batch script, makefile, package dependency file
Reading the README ... and so forth

There is a tipping moment when an aspiring developer goes from seeing a block of text to having developed eagle eyes to see keywords in the text. Around this time, one becomes more accustomed to the navigation of skimming text quickly or reading in depth and knowing whether to speed up or speed down. I don't think it's a normal part of most CS undergraduate education to learn about reading as a way to communicate with other developers. Closest thing I learned in school was in PhD studies where I had cohorts from other fields like social science, psychology, anthropology, and so forth that focused a lot more on interpersonal communication etiquette and had formal ways to articulate the way the human mind picks up new information. The more I think about it, the more my thoughts start to align with Bloom's Taxonomy of learning or Dreyfus Model of skill acquisition.

So far I have only the beginnings of a crude framework for reading skills related to CS education. Note I'm thinking aloud on the spot here, these thoughts will not hold up under scrutiny.

From basic to more sophisticated:

Basic Reading: at the starting level, one learns to read information that's written down. Maybe it's reading the syllabus or homework description before asking questions.
Reading more: at the next level one learns to read more than 1 source because 1 particular text may not be the right fit. To read beyond the prescribed short list. To dive deeper into a topic.
Reading with discernment: reading critically and analytically. Did the author really mean ___? Maybe this part that doesn't make sense is a typo? Perhaps and error message of, "file not found" is telling me something about the filename as input.
Reading with problem solving: in reading with intent, one can ascertain what is and isn't relevant and continue seeking for what is relevant.

Hmm. Maybe these categories don't apply to the activity of programming. When one first start programming, everything looks like gibberish. Over time, one slowly notices the structures (much like Neo in The Matrix) and can follow the patterns. Example from a class on terminal commands:

Exercise 1: Try different commands... ls; ls -l; pwd and so forth

Exercise 2: Try stringing together different commands... pwd && ls -l && echo "hello world!"

Exercise 3: Create myscript.sh and put the commands in a script file.

pwd
javac HelloWorld.java
ls -l
echo "hello world!"

This is where some students "got lost", which as a designer I knew immediately that comments and syntax highlighting would help separate the lines to show it's different commands.

#! /usr/bin/local/bash  
# first line is shebang line to define which shell version to use

# print working directory (pwd)
pwd   # shows path to current directory

# compile a Java file. 
# Won't work because we don't have this file HelloWorld.java
javac HelloWorld.java

# list contents of directory
ls -l  # -l is flag option to show in long form 

# print "hello world" to output
# works like System.out.println("hello world!");
echo "hello world!"

Change permissions for myscript.sh chmod +x myscript.sh

and run the script ./myscript.sh

I think I lost the class again around here.. "Professor I copied and pasted javac HelloWorld.java and it had an error." Hmm..

Ramblings of a CS educator

Kat Chuang — Sun, 20 Sep 2020 17:30:37 +0000

The 4th week of the 16 week long semester just ended (for those who want precision in the calculation - it's a 15 week semester but there are some holidays in between to push past a 15-week span) and it's as good a time as any to record observations else I will forget it until next semester :) I am teaching data structures class, the 3rd CS class in the series (prior 2 courses are on learning programming techniques). Data structure continues to be a challenge to teach, I continue to delve into pondering over why. To set the tone of these observations I want to point out that generally there is a wide range of levels in the class, so the observations don't apply to the whole class. It is by no means a reflection of any particular student performance, but rather my surprise that some things that seem obvious are actually not.

I'm on my 3rd year of teaching data structures class, I am starting to notice common patterns in student behavior. I haven't thought about this long enough to pick apart and think of solutions, wanted to write down thoughts relating to particularly exasperating moments to revisit at a later time. My perspective is one who is coming from industry, especially one that is of high intensity "get things done (yesterday)", not sure how common that is but it provides a stark contrast to the academic environment. I don't claim to know what's the right way to educate CS, I am learning, and certainly my experiences could not be generalized across all towns, universities, programs, nor industries. I am aiming to point out the moments of interesting conflicts in expectations between students and myself.

When there seems to be a fearful attitude towards coding amongst students. It seems that coding holds a certain mystique. I noticed this because it can be one of several ways: (a) when they think there is only one perfect answer, (b) when they lack the instinct to look at documentation but expect to be spoonfed the answer, or (c) they forget coding should be done after thinking through the problem and pseudo-coding. If anything, coding is more like being a legal practitioner, of knowing how to navigate a bunch of rules for various scenarios.
Lack of what I call a "defensive coding" stance (I borrow the term from defensive driving). Some time ago in industry I learned of test driven development (TDD) and it's changed my life in being conscious while coding. That is, think about expectations of input and output with each line written. Keep code that spark joy. I've been noticing a lack of principled technique while debugging code where (a) students aren't thinking to check that file inputs are as they expect before jamming it through their code, (b) they aren't checking the type expected from one line to the next (Java code, so there is a need to consider type strictness).
There is also a lack of systems thinking for constructing a 'pipeline' of functions.. my exposure to terminal commands and functional programming over the years must've helped with visualize a pipeline stream of conversion steps. Students will stare at their code for hours instead of thinking to print output for debugging and think about how one step can be transitioned to the next step.
Not realizing they are authors of source code that is meant for humans to read. They're still at the stage of being hyper-focused in, "I need the machine to compile this".. so much that even when I assign points to homework for documentation and comments specifically they seemingly still forget to add comments 😆 Many these my students could be great accountants with how much they care about points, so that's interesting. Curious if they write comments, would that help with tackling problems directly, swiftly?
Relating to the mystique of CS, a growth mindset may be lacking. Some students have a fixed mindset, they lack of feeling empowered to see that any self-actions can lead to rewarding outcomes. CS educators often talk about breaking larger problems down to manageable tasks and this can immediately apply to a semester of learning. Some students will think as they see the course contents, "I cannot do this, I don't have a Ph.D.," instead of realizing that a journey begins with a single step. That is, they may not know everything yet (sure, the semester just started) but something like 5 minutes to glance at 3 slides that were designed like a picture book can probably answer a few basic questions.

As I write this, I realize I have more thoughts but I will do the healthy thing of taking a break and resuming the musings later because there is still the rest of the weekend to enjoy before the week starts! Ciao.