I’m seeking advice, tips, or tools for planning web apps that are just a little too complicated for me to keep in my head.
I’m building out a feature that essentially lets users contact each other, see who is in their contact list, and see a reverse-chronological list of past messages from a selected contact (among other things).
It’s simple in theory - I’ve been in numerous apps that have this kind of feature (including this forum!), but whenever I start to code the frontend, I inevitably notice something missing from what I thought was a finished backend API. I also stumble upon multiple ways that a user might want to trigger certain API actions - for example a link between to users might be triggered by explicitly adding a contact, or implicitly by attempting to message a non-contact.
The particulars of a lite mail app aren’t the real issue though - what this has taught me is that I need to plan this ahead of coding better, so I wanna know how you all plan your stuff!
I have started experimenting with Trello about a month ago and I think it works rather well for me. I have also just started using Milanote recently for planning and designing, too, and I’m rather fond of the interface. @owel recommended JIRA to me a while ago (original post); I still haven’t gotten around to try it—but I have been thinking about setting up JIRA because it has integration with Bitbucket and GitHub.
In terms of workflow, I usually think through what basic features I need before I start coding or writing anything down. Once I have a relatively good idea of what those things are I create a new board on Trello and go through the same process while noting them down, and when I do this I usually would have many other things to add (it’s almost like when you code or test your app you realise that there are things that you want to implement/haven’t thought about). Then I start coding from there.
I don’t spend time writing pseudocode and/or mapping flow for low-level detail because I’m far from experienced and, more often than not, the actual implementation woud be quite different to the pseudocode I write (or that any pseudocode I write usually wouldn’t be sufficiently similar to the final implementation).
Once I’ve started coding then I use Trello to keep track of issues and new features that I have missed in the planning stage. I try not to get distracted by new issues and features, though, because it would otherwise becomes a rabbit hole and I wouldn’t know what I was originally doing anymore when I come back to it a few hours later.
Perhaps it is worth noting that most of my recent projects were done with React and Redux for front-end—I presonally think that the structure preferred by React and Redux helps with keeping my logic organised. console.log() is also a great way to keep track of things in conjunction with Trello—that way I know exactly which bit of code to go back to later.
One could also potentially use something like bubble.is to prototype an app and use the prototype as a reference, but I haven’t tried doing this yet—it’s just something that I have thought about because I came across bubble.is on a few occasions recently.
Please take it with a grain of salt because it’s only what works for me currently and I’m coding solo. And everything I’ve said so far is only limited to producing an outline that will be used for reference—I don’t mean that one should not spend time thinking about how an API is structured, plan the tech stack for the project carefully… etc. I’m sure my approach would probably change as I get better at coding and/or when I’m working with other people, too.
Initially, I just draw stuff on paper (or whiteboard if that’s your preference). Just pen and paper for quick diagrams and sketches, writing down notes, etc. I have arrows flying all over the place, and notes besides the arrows, etc. (I don’t use drawing/prototyping apps for this activity since I have a tendency to get bogged down using the app itself, or getting sidetracked by other unimportant things, or I just find it too slow to jot down ideas.)
The diagram could be a series of steps needed for a task, or the diagram could be outlining the relationship between different database tables (and related/key fields) to see if it will work or makes sense.
Next step, I start creating the initial database tables and fields, and populating it with some test data (manually entered, or if I need a lot of data, I create a simple program using some Faker data. Then I can populate the database with thousands of test records in a few seconds.
Then I start testing my algorithm, writing SQL queries and manipulating the data to see if I can come up with my expected results. At this point, I may think of adding additional fields in the tables, as I fine tune or I remembered something, or nice-to-have things to keep track of… (sort order, registered Date, IP address, suspended, paid, confirmed, validated fields, etc)
Once I have a working SQL Query, I save this query so I can remember it (and not re-invent it again later). At this point, this is where it’s useful to have some system that can keep track of your notes, bugs, issues, to-do list, etc. As @honmanyau mentioned, I use JIRA app for this… running locally on my OSX.
Next, I’ll start setting up my development environment… creating the local webhost, configuring the web server, creating IDs/passwords for the SQL database, setting up my test local DNS’s (using HOSTS file, named http://projectname.mylocalmachinename.com). I’ll start setting up my LESS/SASS/JSHINT/Minimizer/etc directories and doing a few test run to make sure files are compiled and created in the correct directory. Depending on project, I can use bower, or codekit, or plugins/extensions in Visual Studio, whatever.
I’m sure I’m leaving out a ton of steps in this writeup, but thing is no matter how long/careful you plan it out, it will change as you go along and start coding. You may find out the algorithm you thought out is very slow, or bogs down exponentially when you now have thousands of records of data, or just plain wrong, or you’re trying to implement a new feature and now your initial algorithm isn’t working out.
One thing’s for sure, the best laid out plan will still change and evolve as you start developing your app.
But even an incomplete/imperfect plan is much better than no plan at all.
Write down, sketch charts etc with a general outline. Don’t spend too much time (the plan will be wrong in many ways that aren’t apparent initially), but make sure you have a solid idea of what you want the app to do. Just do it on a big sheet of paper. Try to get a few different flows through the app (what happens when x errors, what happens if you can’t get data from y, what happens when a user successfully competes z and so on).
try to figure out the contexts, the discrete bits of the app that you can build separately - again this is very hard at first, so just get a rough idea, refine later.
avoid dependencies between contexts.
make a prototype as fast as possible: it will be a mess and it won’t work very well. But at that point you’ll have a much better idea of what the difficulties will be.
throw it away and make another one.
break the project up into tiny bits at this point (I would say get it up on GitHub, and use the projects feature: it’s very much like Trello, and you can convert all of the items into issues, and then PR against them). Trello itself is pretty good as well. All you’re trying to do is create a to-do list of tasks that are small enough to be doable.
Stuff like Jira, YMMV but I would advise avoid like the plague: they’re massive, hideously complex pieces of software. They are difficult to use and designed for managing teams: they’re for project managers, product owners and finance departments.
don’t be afraid to dump stuff. Massive benefit of git is that this isn’t an issue, just branch and either dump the branch or merge once you’re done working on it.
do the hard bits first (it is often very difficult to actually know what they are at the start but at this point you should know).
use libraries as much as you want at first. Strip out dependencies later, get stuff built first. UX/UI stuff in particular will distract you enormously unless you’re very strict with yourself - it’s very hard to get right & is a massive time sink. Do what is necessary, polish afterwards.
Figuring out what the contexts are is really important. For example, at the minute I’m writing a registration form. If there are errors when it’s submitted, or if the submission is a success, notifications are triggered in a block at the top of the screen. The reg form and the notifications are two different contexts. Although in my first prototype the two were completely connected, in fact they’re seperate; one doesn’t actually depend on the other. The notifications listen for anything coming in they might be interested in. The reg form just fires off some messages when it gets a response from submitting, and anything interested in them can use them (could be notifications, could be logs etc).
You have different pieces of functionality: users, user messages, the UI to display your app (which can be further broken down), among other things. The code to get the users can be as involved as you want, but maybe the only thing it should expose is a function to get users that allows passing some filtering parameters. Users is one context, messages is another. Maybe - you.might architect it differently.
One specific thing which helps a lot is to constantly refactor code for reuse: modularise it, remove duplication, abstract. Eg for CSS you can put stuff into variables, have a base layer of styles and resets, then some generic stuff like buttons/grids/etc, then more specific styles. JS you.might have helpers and utilities, then generic components, then specific scripts. The primary reason for doing this isn’t that you’ll actually reuse the code that much, instead it forces you to think about contexts, how you structure the project around discrete pieces of functionality.
Edit:
The architecture of open source applications (all available online, and the “500 lines” book is good as well): http://aosabook.org/en/index.html
I usually try to plan all my stuff offline in some way.
I often start out with a brief overview that grows into executiv-like summaries detailing how the idea came to me and what I hope to accomplish being all the aspects and features of the product.
As for planning a sketchbook/sketchpad is immeasurably helpful as I get to spend some time off a computer sketching wireframes directly from my mind, no interface/controls to limit my creativity. It’s even fantastic practice to try coding out some HTML templates alongside a design, or JS logic for how something would work, or MYSQL database to structure data. It reinforces what I know on a computer to be able to write it out by hand with some certainty.
As for my actual workflow, it is currently changing too rapidly for me to be of any use. I am learning how to implement atomic design (a design system methodology) successfully into my portfolio site. I’m planning on picking up a JS templating library, or just mirate from PHP templates and databases to a JS server system with mongo and angular or something. I’m currently a PHP/MySQL server guy combined with the HTML/CSS/JS client.
If you’re hoping to make this app functional I know backend as well as front end. I could help you plan out the schema and help you think about how this would function.
Take a cue from FreeCodeCamp (and AGILE development) and create user stories (see the FCC projects for an example). They are guidelines for the projects here, but you could jot them down as several different user interactions.
Something like
-user is presented with the landing page
-user can create an account or log in
-user can learn about the company
-user can get contact information
-user can learn about our product/service
Then set about adding the corresponding feature for each user story. Something like that can help guide the design process because now you have enough to populate a nav bar.
