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.

I am a graduate student in aerospace engineering. A lot of my Master's thesis has been on developing an OOP software architecture in MATLAB to facilitate control of Arduino-based vehicles (blimps, cars, quadrotors, etc).

All my code is heavily documented, but my thesis itself needs to be more than a reference of every class and method - it needs to describe at a high level how each piece works together, and why my architecture is the way it is.

I only have a minor in computer engineering and I consider myself a pretty competent programmer, but I have no experience writing this kind of document. What kinds of things need to be included in the document? (Diagrams, paragraph explanations of how each class operates, etc)? I don't want to just rehash my code comments (although at the start of each file there's paragraphs of comments about how that class relates to other classes). I also wonder if it's necessary to get rather technical (I implement some fairly advanced MATLAB concepts [that is, advanced for non-computer engineers] such as listeners and callbacks); my audience also hails from an aerospace engineering background.

Examples would be appreciated if they exist.

EDIT: The part my audience really cares about is not the software architecture (the stuff this question entails); this document is really for people who will use my work in the future - who are not computer engineers! So I guess the main question is, what needs to be in the document such that people who are not up to speed on the project (and we can assume competent with the language) can understand the architecture, maintain and use the software?

share|improve this question
3  
"my thesis itself needs to be more than a reference". Your advisor should be able to provide some useful guidance here. We're not evaluating your thesis, so our opinions are largely useless. –  S.Lott Dec 26 '11 at 23:36
    
Well, the part he's really interested in is the application of control of our vehicles. In terms of my research, the software is a bit inconsequential. More than anything, this part of the thesis is kind of a reference for others using the architecture. I'll edit OP to reflect that. –  Dang Khoa Dec 26 '11 at 23:40
    
Examples are numerous. Search for Arduino Software and look at the pages for products you find. You are -- essentially -- building and marketing a software product, right? Have you looked at any web sites for any software products as a starting point? What was confusing about their presentation? Look at Arduino more specifically. Is this a typical example? hlt.media.mit.edu/?p=1229 There seem to be a lot of these. What's wrong with following their approach? –  S.Lott Dec 27 '11 at 11:58
add comment

1 Answer

I currently have the same problem as you, although my software relates to business architecture (Master business engineering).

I'm planning on writing it in such a way that the high-level logic can be understood by someone with basic Object oriented knowledge. I'll be making references to the official documentation, design patters to make it easy for developers to work further on my code. Research papers will also be referenced but not in a way that you would need to read it to understand everything. The papers are just to show what I base everything on.

One tip I want to give you is to make it as visual as possible. I will for example add a scheme with my databaseHelper class at the bottom as a long bar, showing it is encapsulated by my contentprovider by drawing it above also as a bar or around it (it's an android application). This contentprovider will have links to the further abstractions that are made, other classes, ... in such a way that people will be able to understand the whole picture and make abstraction of everything else.

Just begin with the highest level of abstraction and then go down and down. In a lot of cases, if people see the big picture they will be able to make an abstraction of all underlying things and that was the purpose of your paper. You want people to be able to work with it.

So, in general:

-Visualize! -Be technical about the stuff it's really about, the core of you masters thesis. Be clear about everything else so that people can work with it.

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.