Generating… non-documentation

In the last few days I got involved in an interesting question – if you to have an internal conference with 250 presenters, multiple timeslots, live sessions, recordings, materials and more – and you need to create a website for it, what would you do?

One of the obvious choices is to write a custom app for it, has a database (document db or graph db or something similar NOSQL), a 2/3 tier architecture, etc. Or… if I’m anyway trying to understand the options around document generation, I could generate the website from some lousy excel sheets and upload to a CMS that would handle commenting and links and similar.

So I did the latter, using a little bit of XLSX parsing, use of good old Apache (N)Velocity (currently maintained by the Castle team), a little bit of window dressing and figuring out some stupid limitations around transposing arrays with double nested loops using the Velocity language, and:

Blurred image of a generated project page

Please, let me introduce

Another day – another open source project from my team, this time a small nifty tool called “please”, akin something that already been mentioned in one of the ADRs (ADR003):

- We would depend on using an eng/Dependencies.props file instead of having the versions of Nuget files
repeatedly entered into the csproj files
- We would use automated tooling to achieve the maintenance of Dependencies.props file

So, in the end, not only these, but a bunch of other small functionality has been added to this swiss knife of a tool that you can just ask to do stuff, nicely 🙂

It can easily:

  • Consolidate nuget packages across a solution, or only a subset of them
  • Keep package versions in a central props file and maintain that file
  • Move and rename projects
  • Clean up in case you manually moved and renamed
  • Clean up <Compile Remove="..." /> items, with or without globbing
  • To find stray projects
  • To remove ‘junk’ from solution directory
  • To change the PATH variable (useful when working with dotnet tools)
  • etc.

Dr Jekyll & …

Every good project need good documentation, and every good documentation needs a good engine to create and maintain it with.

So, am I going to chose Jekyll for maintaining the (currently mostly empty) ComposeUI documentation site | A WPF .NET Core based, WebView2 using UI Container for hybrid web-desktop applications (morganstanley.com) website? Most likely not. We currently have quite a few contenders for documentation generators – so no, most likely it is not going to be Jekyll our final choice (although nice to have a native support from gh-pages for it for sure, and gives an opportunity excuse to learn a new language and technology, Ruby and the Gems). Contenders are now: Jekyll, Hugo, Docosaurus, Docute, Docsify, Sphinx, Doxygen, etc. Each have their pros and cons, and it is not necessarily that we would only chose one of them. Also, whenever possible, we would aim to generate as much of it as possible – not due lazyness, rather to make sure it is always updated whenever we touch the source code.

So do bear with us, soon we would fill the documentation site with some basic (Jekyll) content before finding out our choice of documentation generator(s).

Why choosing .NET for ComposeUI?

If you do have a working application using Winforms. WPF or similar technologies, your team won’t receive a tangible business benefit from rewriting their existing codebase to web technologies – versus remaining focused on features to drive revenue. .NET on the desktop and WPF specifically looked to be abandoned leaving people in an undesirable state with UWP and Windows 10. The rejuvenated commitment, open sourcing, and full support from Microsoft for WPF in .NET 3, .NET 5 and upcoming 6 have lowered the pressing strategic need to migrate platforms unless appropriate.

To provide features and support for existing and new .NET applications, while simultaneously providing a better and integrated solution for existing and new web applications, the best choice is to remain with .NET. While we did consider to fork Electron or to extend a vendor solution to provide the .NET hosting we need, the amount of work, the resistance of open source maintainers to contributions, and the lack of innersource access make this a showstopper. Disparate window and application interoperability based on messaging alone would be a significant step back in our desktop platform.

.NET (Core) is an open source, multi-platform framework. For Microsoft, it is the future – with the new unified platform pieces (Project Reunion, WinUI 3, MAUI, etc) announced at different conferences, .NET 5 did replace the aging full .NET framework. When it comes to actual business logic, .NET can be used to target Windows, Linux, macOS, iOS, Android, tvOS, watchOS, WebAssembly and many more. The new .NET also solves the standalone side-by-side installation problems that were rooted in Microsoft binding the full .NET Framework to the OS – different versions of .NET Core for different applications can now be run on the same computer. It also provides high performance capabilities throughout the full framework with new language features like Span as well as optimizations within base libraries including but not limiting to Collections, Math, Regex, Strings and File Handling. Nevertheless, should not forget – it is truly open source, Microsoft already merged and released multiple changes that originated from my team, to support custom filesystems, Kerberos edge cases, database drivers, performance fixes, and many more.

Based on the requirements we have, and the direction from Microsoft, we are choosing .NET (core) WPF for now. This decision ties the (pluggable) shell component to Windows only. Of interest is the progress around Windows Virtual Desktop 2.0 (was just renamed to Azure Virtual Desktop). While it remains to be seen whether it is a strategic option, the lock-in has potential to be mitigated. AVD enables accessing cloud backed desktop UIs on non-Windows devices, including support for touch and pen for iOS and Android devices. To support in-house, there has been discussions of making AVD available for on premise (Azure Stack based) solutions as well.

Using AD…what? ADR?

And the ADR for using ADRs is there in ComposeUI/adr-001-use-adrs.md at main · morganstanley/ComposeUI (github.com)


If you are watching the new repo, you might have spotted that the first few PRs are about adding a set of “ADR”s, Architecture Decision Records.


So you could ask, why? You could ask the same question, why a project is using X instead of Y – actually a new person joining a team definitely going to ask the question, why you using Entity Framework and not NHibernate? And believe me, most likely you would hand wave and say “for historic reasons” because you would absolutely not remember anymore. And that’s generally very unfortunate.

Documentation. Yes, I’m also a developer, and I also hate writing documentation. Who doesn’t hate that? Actually, I think, above a given age, when you are being told ‘documentation’ you do have a particular picture in your mind, which is books and books of lot of pages, probably bound together using twines called project documentation while still using Rational Unified Process or Microsoft Solution Framework like I did? Or the other way around, yes, there are tons of documentation, scattered among different systems, hosted off the code, in wiki or something – gets outdated the day you write it, not part of the source control, not structured (or rarely), therefore, why to write it at all, again?

So, documentation, why hate it, but can it be done better? I don’t think I ever started to like writing documentation, believe me. But writing Architecture Decision Records, following a certain scheme in them and keeping them in the same git as my code – that’s more of my liking, believe me. So, just to summarize, an Architectural decision is a software choice. One that addresses either a functional or a non-functional (like project structure – or the fact you do write ADRs!) requirement that is architecturally significant – framework choices, programming languages you choose, OSes you target, data storage, communication patterns, persistence, validation, logging, telemetry; you just name it. Of course, you should not take the term “architecture” too seriously or interpret it too strongly. I mean, look at not-that-recent update of ThoughtWorks’s radar when talks about ADRs: Lightweight Architecture Decision Records | Technology Radar | ThoughtWorks – they went from ‘trial’ in 2016 and speaking about evolutionary architecture to a mainstream adopt in just a few years. And they also suggest to store them in version control instead of wiki/website. Let me finish it with the sentence from the Radar: “For most projects, we see no reason why you wouldn’t want to use this technique.” So, our http://github.com/MorganStanley/ComposeUI is not different 🙂

Ok, so, where is the project?

I got a few people coming back to me after reading the previous post, Going opensource – why?, asking, OK, so, where is the project, how come the repo GitHub – morganstanley/ComposeUI is still empty?

I might have not written it clearly enough OR you might have not read clearly enough the previous post (most likely the former), so this time the idea is that the project would be developer in the open instead of playing a magician’s role with a rabbit and a hat – we wouldn’t just pull up a finished project without the reader understanding the steps we took to arrive to it, rather each discussion, each wrong idea, etc would be also developed and showed in the wild open.

I hope this helps regards some people who quickly just clicked through the link at the top of the previous post, waiting to see the actual project – yes, this is not exactly the case here 🙂

Going opensource – why?

Small update on Ok, so, where is the project? added as a separate post 🙂


I suppose you haven’t spotted yet – we just created a new opensource project, GitHub – morganstanley/Compose . It might worth explaining the why behind that choice.

It is always appropriate to challenge the need for a project to be open source, given the lack of foreknowledge of anyone else having a desire to use a platform versus the other possible options or their own proprietary one. While we have the desire and the capability to support this if it comes to be, it’s not the primary motivation. With a foundational architectural aspiration of a pluggable platform, it’s important for it to be possible to selectively choose components from open source and if needed, from commercial vendors that make sense given your requirements. There is no reason for a company to own every line of code or to find something available that tries to meet all our needs. Vendors will always yearn to get their foot in the door and being open source accelerates and simplifies partnerships through increased visibility and collaboration without the red/yellow tape or proprietary integrations or NDAs. We have already seen this model work successfully with other projects like desktopJS as ongoing collaborative efforts with vendors to use and extend simply for their own (sales) demos to others. While it is naïve to think they aren’t also doing this to make it easier for us to choose their platform. It has proven the usefulness of open source being successful in other ways than just marketing, recruiting or reuse by others. It is also a tool to better work with the industry to outsource or “buy” features off the shelf that give a commercial momentum with faster delivery. Having this project in the open is also useful to drive the roadmap of some companies by adding use cases that finserv developers need and expect.

Open source also provides us with innovative methods to explore different avenues of staff augmentation – e.g. working in an open manner eliminates the onboarding needs as well as associated overhead resulting in immediate participation and contribution.

A tangential benefit of being open source is keeping us free of binding ourselves unnecessarily to internal tooling and processes and implementation. By using off the shelf build infrastructure and GitHub capabilities we will be able to swiftly adopt and leverage industry leading DevOps tooling.

So what does open source mean to me? Whether you are operating on the cloud or on premises, you want to spend most of your time on solving the business problems in front of you, not on re-inventing the wheel of algorithms, APIs, pipelines, deployment and so on. Fortunately, we get to stand on the shoulders of giants by relying on robust well-maintained open source libraries or specialized vendor software, when appropriate. Most of the popular modern solutions work equally well on the cloud and in an internal infrastructure. In our view, .NET developers should be working on problems that are critical to the functioning of the company, and it’s the job of projects like this one to enable that focus by providing the functional foundational building blocks. We do help finding and creating the robust solutions to the generic problems so practitioners can remain focused on the aspects that are specific to their business. By developing battle tested code, harnessing the brain power within the OSS community and building relationship with selected vendors, we are able to provide the best-in-class tools and libraries for all .NET Developers. This amounts to less custom code scattered across, that becomes a technical debt, and results in an easier learning curve for anyone joining a firm – like ours.

Where customizations are required of other OSS projects, we promote contributing those changes back to the project on the firm’s behalf – this is in line with the overall firmwide OSS strategy.

We are doing .NET Core – .NET Core itself is a fairly young technology and the usage of it is also at the very beginning of its journey. Our mission, our approach and our thinking will evolve as .NET Core adoption matures and as the subject itself evolves. This will always be a collaborative effort and we do invite input from all of our constituents. This input allows us to be better informed and to better understand the needs of practitioners around the world. My group, my team will strive to be a resource for .NET Core expertise on desktop, cloud, software, vendor needs, advanced techniques, academic research and related topics. But for this, we need to go open source 🙂

Morgan Stanley at Microsoft //Build’21

After having our logo up last year and being talked about, and being showed as part of the 2014 Build keynote (What kept me busy recently #4), this year we would be again part of //Build – this time my manager, Dov Katz is going to be interviewed by Ben Walters, we even got a real aka.ms vanity URL, http://aka.ms/msbuild_morganstanley 🙂 Beside this, it’s expected that even I’d show up for a short segment speaking about the WebView2 journey as part of MyBuild – Microsoft Edge: State of the platform 🙂 And as above, Dov as part of MyBuild – Morgan Stanley joins Customer Tech Talks to discuss operating at the speed of international finance with WebView2.

Opportunities in the .NET Team at Morgan Stanley

We are on the verge of making huge sweeping changes – moving to Linux, moving to .NET Core, moving to Azure, moving to Edge control, moving to open source etc just to name a few. We are a small, highly skilled team of .NET experts, whose role is to set the technical direction for .NET, collaborate with the development teams to encourage the adoption of best practices and provide specialized set of proprietary libraries. The moves above – moving to open source, to the cloud, etc – are some of the biggest changes we faced, and the roles below provide the opportunity to help set the direction for the next generation of .NET applications. We are looking for passionate technologist with design skills, strong CS fundamentals and a deep knowledge of .NET as well as a curiosity about what is happening under the hood – how, why and what are the questions we answer on a daily basis.

We offer:

  • Opportunity to challenge yourself by solving some of the biggest technical challenges in Morgan Stanley.
  • Chance to be at the forefront of Morgan Stanley’s adoption of latest platforms, tools and techniques.
  • Insight into how technology is used in large scale enterprise deployments through collaborations with multiple teams across the firm.
  • Opportunity to look ‘under the hood’ – how, why and what if are questions that we answer on a daily basis.

You will collaborate with your team to:

  • Design and implement the next generation of our proprietary libraries, tools and components to support more modern architectures.
  • Provide direction and define best practices for designing modern applications for all the firms developers.
  • Work with application teams to identify and adopt the best solutions for their use cases.
  • Provide technical solutions to adopting new techniques and libraries which interface with existing deployments.
  • Increasing our involvement in the Open Source projects that we rely on.

You have:

  • Solid .NET C# experience.
  • Strong fundamental technology skills (OO design, threading).
  • Server side, WPF or Winforms experience.
  • Ability to converse verbally and in writing in English with other .NET developers on complicated technical requirements.
  • Have an interest and aptitude for technology.
  • Can adapt to a dynamic and multifaceted environment where business and technical skills are intermingled.

You may also have:

  • Knowledge of .NET Core.
  • Low level networking knowledge.
  • Advanced debugging skills.
  • Knowledge of development in sandbox environments.
  • Focus on User Experience.

If you know someone who might be interested please get in touch with peter (.) smulovics (at) morgan stanley .com .