Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
That's what I am asking, how do I organize my thoughts on paper or in notepad so that I am making the most of my time by not only allowing myself to think about the problem but also creating something I can refer to usefully. –  dah Sep 21 '11 at 16:53
    
I believe it is, I don't want to pidgin-hole them into talking about pen and paper notes, if someone says, use a UML diagramming application and makes a reasonable argument, I would like to explore that as well. –  dah Sep 21 '11 at 17:23
1  
You may consider using mind maps to organize your notes, at least in the initial (analysis) phase. –  Péter Török Sep 21 '11 at 17:26
    
@dah: "pigeon-hole" it's a bird's nest. "pen and paper notes, if someone says, use a UML diagramming application " are all technologies to implement some goal. What's your goal? Given a goal, we can pick technologies. With no goal, nothing good can happen. Please define your goal, objective, end-game or outcome. –  S.Lott Sep 21 '11 at 17:28
add comment

6 Answers

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.

Good luck.

share|improve this answer
    
What does BA stand for in this context? Business architect? –  user937146 Sep 21 '11 at 19:29
1  
@user937146 - Business Analyst. –  P.Brian.Mackey Sep 21 '11 at 19:54
    
Ah, makes sense. Thanks! –  user937146 Sep 21 '11 at 20:59
add comment

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.

share|improve this answer
    
This is interesting, I know basic uml but I find it kind of hard to recall all of the particular symbols when referring to relationships. –  dah Sep 21 '11 at 17:26
add comment

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.

share|improve this answer
    
This is a helpful response, how do you put this into a form that you can refer to? Do you write paper notes, use UML, some kind of TODO list application? –  dah Sep 21 '11 at 17:25
add comment

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)

share|improve this answer
    
Thanks for your response, Tom. I agree that I take poor notes, how do I improve that? Do you mean paper prototyping or mockups or UML? –  dah Sep 21 '11 at 16:54
1  
I mean actual code prototypes. Have a look at the pragmatic programmer amazon.co.uk/Pragmatic-Programmer-Andrew-Hunt/dp/020161622X –  Tom Squires Sep 21 '11 at 16:57
    
I think I'm going to buy this book, it looks promising. –  dah Sep 21 '11 at 17:23
add comment

I make notes but they're not very useful, how should I organize my notes[...]?

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.

share|improve this answer
add comment

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 :-)

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.