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.

For my next project, I'm looking to document my Object Oriented design in simple text before jumping the gun to code it up. I want to do this for two reasons.

  1. I want to give proper thought to my design and possibly revise it several times.
  2. I haven't exactly decided which language I want to implement my project in.

I'm looking for a convention to outline my design in simple text, instead of a UML diagram. I like the convenience of text. I can version control it and easily put in a blog or wiki to share it.

I am thinking something concise e.g. how you might code in Python. However, I want the representation to be language independent. I've looked around the internet but couldn't find anything. The closest would probably be how properties and methods are defined in the box representing a class in a UML Model.

Update: I just wanted to clarify "in Text". My goal is to be able to outline the object model in a github wiki. I imagine it being kind of an open source design in addition to code. Thus, I can create a Wiki page per entity and identify the relationships using links and formatting etc. However, what I wanted suggestions on was how to outline the specification of an entity on its page.

share|improve this question
    
How are the requirements your design is solving for documented? –  Telastyn Jul 17 '12 at 18:44
    
@Telastyn The requirements are not formally documented. The requirements are basically my idea of a new project that I wanted to work on. –  Danish Jul 17 '12 at 18:47
2  
Don't use just text. It is difficult to express relationships and interactions the way UML and sequence diagrams can. You can use a text based UML tool like UMLet. –  Oded Jul 17 '12 at 19:10
    
Javadoc, with its hyperlinks, is really great for this. Unfortunately, it's kind of tied to Java. –  RalphChapin Jul 17 '12 at 19:33

3 Answers 3

up vote 6 down vote accepted

You could write in HTML and use hyperlinks to express relationships between different classes. The problem, though, is that you can't see links. When documenting a design, the relationships are a big part of what you're trying to explain, so it won't do to make them invisible.

I'd suggest forgetting about plain text. Use HTML at a minimum, and don't be afraid to include pictures created in your favorite drawing/graphing tool. These may not be quite so universal as plain text, but you'll still be able to view them in any browser, and you should still be able to track them in a version control system just fine.

share|improve this answer
    
You've read my mind. I am actually hopping to outline the design on a github wiki. Sort of like an open source design in addition to code. I am hoping to have 1 page per entity, just wasn't sure how to outline content in each page. I guess the way I asked the question is not entirely correct –  Danish Jul 17 '12 at 20:36
    
+1. And don't underestimate the power of pen and paper. –  StriplingWarrior Jul 17 '12 at 20:39
    
@StriplingWarrior - I would love to use pen and paper. Its just that I wanted to make it easy to share the design. –  Danish Jul 17 '12 at 20:47

We had a huge project and I documented all of the teller functions using Use Cases. So we had Deposit, Withdrawal, etc... with each one it had several local, mid, and backend processes to go through. At various levels I also had access changing by security. The use cases made all of that quite clear and allows you to document not only the system but also the players involved. Helps in determining what areas you need to design class libraries for and what different security comes into play.

That high level view makes it very easy to a) document what is happening -- as well as -- b) identifying potential sub systems you need to design/construct. It will, in the long run, make your next level of design much better (IMHO).

share|improve this answer
1  
There is no doubt that Use Cases are important. However, I don't believe use cases are an alternative to an Object Model. –  Danish Jul 17 '12 at 20:40

The closest things to what you want are Use Cases. These represent a textual representation of the requirements, ideas and design of your application. A simple explanation can be found here at wikipedia.

However, for best documentation I recommend Alistair Cockburn's Writing Effective Use Cases book.

share|improve this answer
4  
Use cases are what you design for, they are not themselves a design. –  Caleb Jul 17 '12 at 20:21

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.