Teaching Software Architecture with GitHub

I think there is none.

I think every organization is different. The best thing to do is be communicative, responsive and honest. Moving agile means all the above. Rule one is start small and go simple. Just spent three days on making something and I got stuck so I said fuck it, start small. So I need to build this tool that reads the output of another tool. Sadly it comes out in terminal with all kinds of custom format. Instead of parsing the full "terminal output" I receive, I start small by reading and getting whatever I need. Gradually I built up the "reader/parser" I need to from this report I was trying to parse. And I finished what I was hoping to finish.

> Also when you're doing sole projects are there specific procedures you should follow and how do they differ from when you're in a team?

It's very subjective. I think if you are accustom to one way you do it that way more often. But I said in my example, I spent three days trying to go complex. That's the failure of me, but it probably happen to everyone everytime because I (or we) think I was smart so I could solve this complex issue. The only rule I have when I do sole project is to define the scope of my project. I write down whatever I want to implement, what it does. Essentially building up a set of user stories for myself. But that's also true for team project. You just can't be sloppy and acting alone when you do team work... so when you work with others, get the user stories up and running, figure out the style you want to code in... they all matter.

Last thing: it's easy to say, but it is damn hard to do it. Just relax.

In terms of books, I really like "The Architecture of Open Source Applications" (http://aosabook.org/) which is also mentioned in the blog post. For the enterprise world, "Patterns of Enterprise Application Architecture" (http://martinfowler.com/books/eaa.html) is a good choice.

However, before applying any technical software architecture methods, it is really important to understand what your stakeholders actually want/need. Unfortunately most of the time they don't even know it themselves. In my experience most software projects fail, not because of technical reasons but simply because the original problem hasn't been understood. This is where communication is key. I assume the reason why the authors of the blog post encouraged drawing diagrams and looking at different perspectives/views is to facilitate this communication.

This fellow: http://www.jonathanholloway.co.uk/work

Wrote his master's thesis on the very subject http://www.jonathanholloway.co.uk/thesis/abstract.html

[Whole thesis back in /work]

I think even just making demos and making documentation changes is equally powerful and useful contribution.

We advised the students to look critically at recent open (or just closed) issues and pull requests, as well as e.g., the mailing list for the project at hand. Based on that they could get a feeling what was happening at the moment, and what a typical contribution looks like.

If you want to contribute code, we found that it works best if you work on parts of the code that are currently under active development. This also means that you do not have to have a deep understanding of the full code base: A broad overview suffices.

Some of our students also offered documentation for, e.g., installation or deployment: they struggled themselves, and offered what they learned back to the project.

For example, you have given links to a couple of github repos. Now if I'm trying to create an overview of how say emacs works, I would try to identify the main sub-parts and break the system down into more manageable chunks of study. This is all what 'viewpoints' are trying to structure. None of this is evident from just the codebase unless it has been captured in some documentation, or you take the trouble to understand it yourself.

You seem to have a very low opinion of software architects, but believe me, you wouldn't want to work on a 5-year old system where huge teams of developers have let loose and no one/team was responsible to ensure a cohesive, maintainable system.

Viewpoints are fantastic for communication purposes, and if you feel that the particular viewpoints shown don't make much of a difference, I agree :). A student project is also not the ideal environment, but it is really valuable to know how to create them, considering the information needs of the audience (biz vs tech vs in-depth tech). And that is what this course is all about.

Sorry I have to counter-react strongly. Your post is negative without a valid point and the irony is that you agree with the post.

> One can learn much more from walking through the actual source code of some classic projects and from trying to understand what makes them tick

That is the fun part about this post! You propose to mandidate a list of classical code bases. This course lets students freely pick any Github project with activity and complexity. They get graded based on pull requests.. Contributing code and interacting with an Open Source project you picked a week ago is not "drawing pictures" and "connecting them with arrows".

Thanks for your feedback.

Perhaps we did not sufficiently emphasize it in the blog post, but we do tell the students about strong existing architectures, open source as well as from industry. The books listed in further reading in the post actually contain chapters about git and emacs, and I share your enthusiasm for Bentley's little language approach.

The philosophy of the course is based on trying to apply published approaches to software architecture (such as those in Rozanski & Woods' book, but it could be others) to real systems actually maintained and used. We encourage to get in touch with the creators of those systems.

The students actually take a deep dive into a foreign code base -- I included pictures because that is easy to share in a post, but the students analyze code, report about that, execute test cases, deploy systems, etc. The pictures are indeed, as suggested by some of the others, means for communication.