How should I document my designing of the app better so that I avoid programming by coincidence? How can I structure notes so that it is clear how an app works so that when I refer to it a year later I'm not lost for the first 3 days?
- Anybody can ask a question
- Anybody can answer
- The best answers are voted up and rise to the top
closed as too broad by gnat, MichaelT, Dan Pichelman, GlenH7, Jonathan Eunice Dec 10 '14 at 19:08
There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.
Separate the Analysis from the Design. Don't let architectural issues intrude on the requirements. Take your notes from an outsider's perspective, what will they see and where does that data come from?
You should spend more time on your notes, not less. You can't create the architecture to fit partial notes, that's like designing clothes for a mannequin missing both legs and an arm, sure it's fast but (as you've noticed) it's hardly functional ;-)
Read up a little on UML, even if you don't use it to sketch out your app the methodologies that use UML will provide you with inspiration.
Applications consist of at least two major sets of requirements: Business and Technical. Business Requirements come first and should describe what the application needs to do and the business goals it will solve. Having a good set of Business Requirements often requires not only understanding what the user asks for, but also what the user really wants. I mean, a non-technical person often cannot express bus. req's clearly and fully without the help of a qualified BA (one that understands the particular Business at hand).
Assuming you are a qualified BA and you have a complete set of Bus. Req's. Then you need to drawup a plan to build the product, technical requirements. There are many paradigms and approaches to managing a project. You should pick one that works for you and the team, say Agile.
I recommend drawing out the Entities required to solve the Business Requirements. Then, take a divide and conquer approach to implementation. Red-Green refactor works quite well for division of labor.
For example, an Employee is an Entity in your product. The Employee needs CRUD operations. Create an CRUD interface, and a unit test for each of the 4 CRUD elements. The unit tests all fail at the start. Then, delegate a programmer to implement the CRUD operations of the Employee entity until they all pass.
Rinse and repeat. Assuming you have properly identified all entities, this will bring you well into the last phases of back-end development. Add helper classes and a common library, keep unit tests updated and over time the products will improve and development will be faster.
Finally, decouple front end work from backend by using Inversion of Control. Do up your CSS and all that jazz with mock data until complete. Then, plugin the backend.
That's how I like to do things at least. Keep in mind, there are no "right ways to build a bridge" in software. Each team is unique. Each project is unique. Paradigms and standards are guidelines set by developers who solved particular problems in a particular way and said solutions stood the test of time.
Bear in mind that my answer reflects my strengths and weaknesses, which may not be yours.
I divide programming into three parts 1) syntax (defining variables, read-write operations, etc.), 2) computations, and 3) logic.
My big weakness is in the math/computation part, so I try to get help on that from others. Specifically, I will try to get the user, typically an engineer, to write out all the relevant equations and computational formulas for me. Absent such help, I may consult a textbook, or use a programming library.
My strength is in languages, so I tackle the syntactical issues on my own: variable definition, formatting, layout, etc. This is much easier, if I've followed step 1 and had the engineer define the problem for me.
The last area is logic: branching, loops, links, test conditions etc. This is my area of intermediate difficulty, which is why I tackle it last.
This advice may not work for you in its exact form. But the idea is to identify your strengths and weaknesses, and get any help you need in the latter area.
If you're not good at note taking (and it sounds like you're not) then I would try prototyping. Sketch out a rough plan then spend a couple of hours to see if it's a good idea. You can then use the prototype as a plan of how your production should work. (do a rewrite)
You need a bug tracker.
If you want to start a project, report it's Elevator Pitch as a bug! Attach each important feature to support that goal as another bug.
If you've got written notes, either ideas you've brainstormed, or minutes you've taken from a meeting with a customer, those need to make it into the bug tracker as soon as possible.
The value of organizing your project plan in this way is that you can easily search and organize each task according to how it relates to other items, how urgent it is, how much you've completed. It also allows you to link the changes in the source code back to the factors that influenced them; this change fixes that bug or implements that feature.
You can use a class diagram for documentation purposes. I don't mean to generate an automatic documentation using UML which is really crap but to create manually class diagrams views of your packages.
You don't really need to know UML because if you reverse your project then you get your model and a class diagram for each package. You then just add notes on classes and methods. You save your diagram directly at the root of your package. Job done !!
Really easy and very efficient. This is what I do and developers love me :-)