6

I'm working on my CS Masters thesis at a company which does user interfaces in the field of embedded devices. As part of that I am developing a library for integrating a certain device. My C++ library wraps the device drivers and integrates the device's features in the Qt framework so that it can be used with a variety of Qt/QML-based applications.

So far I have written many notes and detailed API documentation (using Doxygen). But I have no idea how to properly format all the information in order to provide a good overview of my work in the thesis. Simply using the API documentation doesn't make sense since 1) it's way too detailed and 2) doesn't exactly give a formal overview of how things are structured and work together.

From what I know I have to describe at least the following aspects of the software product I'm developing:

  • Technology(ies): which technologies I have used. I have split my project into:

    • a library which provides device management, data conversion, and Qt integration;
    • tests; and
    • a collection of ready-made Qt widgets which use the library.

  • Patterns: what software patterns I have used (MVC, Singleton, Factory, Observer etc.). The problem here is that there are many, many patterns out there and there is a known inconsistency when it comes to which pattern is what exactly (alone the MVC pattern is very famous for it - pick three books from different authors and there is a very high chance that the descriptions of this pattern vary greatly!). Personally I work following the principle "XYZ makes sense to me hence I will use it", which probably many of you will find too broad. :D

  • Information flow: mostly sequence and flow diagrams here: if user does action X how does the device and the rest of the system respond to it.

  • Data management: for storing and processing the data from the device, my library uses data containers such as arrays, vectors, hash tables etc..

I doubt that this is enough or even correct that's why I'm asking for help. I was unable to find a step-by-step tutorial that I can follow. I also don't know how deep I have to go.

I have asked my professor about the hardware-level stuff and he said that he doesn't want to see that in the thesis and that I should concentrate on what I am developing.

However this restriction only helps a little bit since Qt framework alone has a huge and complex structure. For example if I use a QVector3D do I have to actually describe in detail what this is and how it's managed or can I assume that a simple "A container for 3D vectors" would suffice?

Frankly, we have studied various software architecture related things like patterns etc, but we were never shown how to formally describe a software system. All I did previously was short lab reports and API documentation + some evaluation statistics about performance.

Improve this question
7
  • If you replace "Master thesis" with "project at work" and it's magically on topic, then this question doesn't deserve a downvote. I think this is a very answerable question, but each bullet point might be good as its own question to help narrow the focus. (I'm not the downvoter, btw)
    – Greg Burghardt
    Jan 10, 2017 at 12:42
  • 1
    The thing is that at work there is no template that I can use (I do the thesis for a company). On the other hand a Master thesis has a different format compared to some documentation that you find in the manual of that product. That's why I have specifically also added "Master thesis" because the format (and not only the bullet points) is important. Perhaps I'm wrong about that...
    – rbaleksandar
    Jan 10, 2017 at 12:46
  • 1
    My point wasn't that "Master thesis" was the wrong thing to put in. My comment was aimed mostly at the downvoter. :) I feel like people tend to be unfairly harsh towards questions about the academic community instead of business.
    – Greg Burghardt
    Jan 10, 2017 at 13:02
  • 1
    LOL That might be true. I'll add what I wrote in the comment section namely that the thesis is done for a company to add a more...practical aspect to my question.
    – rbaleksandar
    Jan 10, 2017 at 13:04
  • Have you read the following? en.wikipedia.org/wiki/4%2B1_architectural_view_model
    – Bryan Oakley
    Jan 10, 2017 at 14:29

3 Answers 3

Reset to default
9

Consider using 4+1 Architecture view to describe architecture of your software.

Summary of the views is given below:

Development view: An implementation view from software developer perspective. UML Diagrams (such as package diagram) could be used to represent this view.

Logical view: It provides functional view describing functionality that the system provides to end-users. UML diagrams (such as class diagrams, and activity diagrams) could be used to represent the logical view.

Physical view: It reveals a system engineer's point of view. It is also referred as the deployment view. Deployment diagram could be employed to describe the view.

Process view: It captures the dynamic aspects (concurrency, runtime behavior, etc.) of the system. Activity diagrams are suitable for the view.

Scenarios: Scenarios (or use cases) describe sequences of interactions between objects and between processes.

Improve this answer
4
  • Thanks, this looks like it covers everything in a nice way. I will give it a shot. For now I'll mark your answer as the accepted one.
    – rbaleksandar
    Jan 10, 2017 at 16:40
  • I actually found an easier to use model namely the layered architecture model (I'll take something very similar to the .Net Micro Framework). Still, will leave this as the answer since it can also be applied.
    – rbaleksandar
    Jan 12, 2017 at 5:44
  • 1
    You may use layered architecture model diagram if you adopted "layering" as the architecture style in your code (and there are many architecture styles such as "pipe and filter"). Also, layered diagram only provides you one perspective of the system. If it is enough for your purpose, it's well and good; however, many times it's not sufficient.
    – Tushar
    Jan 12, 2017 at 9:25
  • I actually have it in my code. Just didn't know how to call it. :X It fits really nice. As for the "one perspective of the system" I'll make sure to add a bunch of things from the 4+1 model (for example sequence diagrams to show how the various features of the whole system works). Thanks again! A combination of your suggestion and the layered model seems like a perfect fit for what I want to do.
    – rbaleksandar
    Jan 12, 2017 at 10:28
3

This question has multiple correct answers so I will leave the one @Tushar gave as the right one.

In my case a mixture of two models fits quite nicely. Up until this moment I have actually been working with a layered architecture model. A confirmation of it being "the right one" for my case came to me while I was browsing for more information and found the .Net Micro Framework:

enter image description here

My system has a very similar layout (except that instead of .NET I'm using Qt). However this model doesn't include something that the suggested 4+1 view model has namely the Scenario view. So what I'm going to do is to use the layer model to describe the general structure of my system, add UML (mostly activity and sequence) diagrams to show how input and output are being processed and last but not least add a section for scenarios which outline features that my software offers.

I find the layered model to be relatively simplistic (unlike the 4+1 view model where you have to specify a lot of things that you normally wouldn't bother putting in a thesis) yet offer a nice overview of a system especially when it comes to interaction between hardware and software.

Improve this answer
2
  • The layered architecture is an architecture style. Your architecture seems to use this style, with the layers GUI–Widgets–Library–Drivers–Microcontroller, with your work being the middle layers. In contrast, the 4+1 view is a model for describing architectures. A diagram of the layers would fit well into the development view.
    – amon
    Jan 17, 2017 at 13:42
  • 2
    There is no right or wrong answer to the style of describing an architecture. Architectures can and should be portrayed in multiple viewpoints. @Tushar describes different types of views that can be used to describe an architecture, and layered is just one of those types. The correct answer when it comes to architecture IMO is to describe as many views as clearly and succinct as possible to properly communicate architecture and design to all project stakeholders.
    – maple_shaft ♦
    Jan 17, 2017 at 13:56
2

You need diagrams. A good diagram is better than a wall of words, and can be pasted into any document (including a thesis). UML class diagrams are an obvious starting point. Add other UML diagrams if they are useful to you - such as package diagrams, use-case diagrams or sequence diagrams. Maybe use other non-UML types of diagrams if you want.

Once you have the diagrams, you can write the words around them.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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