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.

  • 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. Jul 17 '12 at 19:33

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.

  • 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. 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).

  • 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
  • @SASS_Shooter: can you post a link to any tutorials or posts to learn about usecases? Oct 26 '15 at 1:34

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.

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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