Improving Windows Developer Experience

[akeller]

We have some internal threads going about using zbctl terminal commands in Windows cmd, when those instructions leverage Linux or bash only commands like source. There is no direct alternative to source on Windows. We have some options to correct this, but I'd like to open this issue to discuss. The following options can be combined.

1. Change the text on the page to mention source as a Unix-only command. Lowest effort
2. Recommend users install Windows Subsystem for Linux and even work with Windows Terminal to have the best compatible client & shell experience across our docs. Low doc effort, burden shifted to devs/users
3. Offer modified instructions compatible with Windows cmd Low effort, but could present maintenance issue

This also opens an interesting discussion around how many users are using Windows as their development environment and how much flexibility they have in using option 2, for example.

Additionally, option 3 runs us into some other open questions. We can suggest users directly enter their credentials via flags wth zbctl status but is that the recommended way for a production scenario?

Looking for thoughts from anyone, but particularly menski jwulf @felix-mueller.

[meyerdan]

Hi Amara, just quick thought: Option 2 is not an Option for me because of the following reasons:

• My experience is that in larger organisations, developers are often not allowed to make such changes to their machines (I think this is what you mean with "how much flexibility they have in using option 2)
• It would assume that these developers actually have UNIX knowledge which is also not the case in my experience

We should "Meet developers in their comfort zone" which would clearly point towards Option 3 in my opinion.

I am also thinking that beyond this, we should probably define Windows as the default environment that we target for dev environments, followed by Mac and then linux. This is purely based on gut feeling however and we should back that up more thoroughly.

[jakobfreund]

Basically agree with Daniel. Another way to phrase this:

a) Do we think that Windows is an actually relevant OS in our target audience? My gut feeling is "yes, absolutely", simply because of my personal experiences with our customers (where I've seen Windows being the mandatory OS a lot of times), plus the fact that we offer a C# client which I think doesn't make sense outside of the Windows universe (maybe I'm wrong).

b) If the answer is "yes" we should not support those developers halfheartedly (like your option 2) but do all we can to provide an amazing experience (basically option 3)).

We can of course put more efforts in a) (like "data driven decision making") and validate the hypothesis about the relevance of Windows for our audience. But we can also just take the shortcut, simply assume that and move on to b) which would mean we would make an improvement right way and also save time that we can spent elsewhere.

I also agree with Daniel's other suggestion (Windows is default assumption, then Mac and then Linux).

[jwulf]

a C# client which I think doesn't make sense outside of the Windows universe (maybe I'm wrong).

C# is cross-platform now, and you can run it on Mac OS and Linux.

Option 2, "how to Linux on Windows", is how many developers who can, do develop on Windows. So this is the best way for those who can. To achieve this, we could point developers to existing articles on this, such as Windows Subsystem for Linux Documentation.

For those who can't (because of organisational limitations), the best way to support them in Option 3, is to build the zbctl binary to support the kind of configuration that is idiomatic to Windows. These methods are listed here: Configuration in .NET.

The first one is Settings files, such as appsettings.json.

Issue #3544 in the Zeebe repo is for configuration via json.

This would give us a single method for all platforms. We could keep environmental configuration, which is idiomatic for Mac and Linux, and support JSON config file across all platforms.

[akeller]

The biggest question I have is with current users (developers) of Camunda Cloud (Zeebe) - Do we have Windows users internally and externally to test? Personally, my work computer is a MacBook Pro but I have access to a personal Windows desktop. This is what I mean about maintenance. If we aren't regularly testing on Windows, this quickly becomes tech debt.

[jakobfreund]

Option 2, "how to Linux on Windows", is how many developers who can, do develop on Windows. So this is the best way for those who can.

How do you know this? This seems to assume that every developer knows Linux and likes to use it, which I've never seen validated neither by data nor by anecdotes (I've seen plenty of counter anecdotes though).

[jakobfreund]

Do we have Windows users internally and externally to test?

Happy to volunteer - I use Windows - and I assume @berndruecker does too.

[berndruecker]

Ping me if you need help - happy to volunteer too. I am Windows User by heart :-) While I do use the Ubuntu/Linux subsystem it is just because some tools simply don't work without and many tech hippster tools don't bother to describe the process on windows. But I also doubt that all windows developers want to do use SWL - I would even assume that many windows developers don't even have the rights to install/activate WSL on their cooperate machines. Given our target group, I would not make any assumptions here but try to provide a smooth experience on Windows too

[jakobfreund]

let me emphasize the point about our audience by tying this to our general strategic positioning in the market: Our mission is to help big, established enterprises to achieve gradual digital transformation, so they can move away from their legacy systems world and become a digital enterprise. That means we need to pick them up where they are. Our developer personas are most often not the highly skilled, passionate developer that might have embraced Linux back in the 90s, nor is it the twenty-something developer that has never used anything else than a MacBook and would typically join a fancy startup like Camunda, but rather not Allianz insurance or Bank of America. But our customers are Allianz insurance and Bank of America, and the developers over there use Java or .NET (and increasingly Javascript, though rarely in the backend I guess), and at least on their personal Workstations they're running Windows (mostly because they have to but I guess also very often because they want to).

So that's the sort of audience we need to have top of mind and empower, even though we arguably provide quite cutting-edge technology with the latest and greatest things like GraphQL etc. It's a balance to find, but if we're able to provide that bridge we're going to take their hearts by storm :)

[jwulf]

Option 2, "how to Linux on Windows", is how many developers who can, do develop on Windows. So this is the best way for those who can.

How do you know this? This seems to assume that every developer knows Linux and likes to use it, which I've never seen validated neither by data nor by anecdotes (I've seen plenty of counter anecdotes though).

See this Reddit thread for some anecdotal experiences.

Highlights:

Honestly I suspect one of the biggest bonuses is that generally instructions on how to do things aren't written for Windows users. So you run into problems where every time you hit a snag compiling or installing something it takes longer to figure out.

More importantly, I can code for one type of distribution, and simply refer Windows users to WSL.

There is also the personal testimony from a German developer above (although he works at a fancy startup, and probably isn't in our target market... ;-) ). That seems to be the motivator when developers have the option ("because some tools simply don't work without and many tech hipster tools don't bother to describe the process on windows"). I mean, basically the very existence and continued development of WSL is a concession to this situation.

When I was doing technical recruiting in Brisbane, I dealt with developers on .NET and JS stacks, and the Windows developers among them used WSL. Same thing with the Node.js and PHP devs on Windows at CreditSense. Most of the devs that I met in Australia at conferences and meetups were using WSL on Windows (but they are going to be passionate).

It may be different in Europe, in large corporations (like Telstra in Australia), or in the Java ecosystem, but when I met Windows devs who could choose it on .NET Core and Node.js, they were using WSL on Windows.

As a counter-point, this Reddit thread has Java devs hating on WSL.

So maybe we should check in our target market to see what percentage of people can / are using WSL?

Has anyone opened a support ticket about Windows support / instructions?

This question in the Camunda Cloud forum was solved by directing the user to use WSL. A caveat though, the historical Zeebe community will probably be skewed, because tech hipsters.

[jwulf]

The biggest question I have is with current users (developers) of Camunda Cloud (Zeebe) - Do we have Windows users internally and externally to test? Personally, my work computer is a MacBook Pro but I have access to a personal Windows desktop. This is what I mean about maintenance. If we aren't regularly testing on Windows, this quickly becomes tech debt.

I was testing on Windows over a year ago, using a VM. To be honest, I stopped because it was such a PITA to do anything except use WSL, and I was like: "Well, if you are using WSL, then you don't need Windows-specific instructions".

I haven't had anyone ask about it for the Node client. I have for the Docker compose images, but not for more than a year. I think we should validate demand before committing to supporting a separate environment.

Specifically with zbctl config: if we can get JSON config file support - which is used by other tools like the aws-cli (although they use YAML) - then we have a cross-platform solution that will also work for those Windows users who cannot use WSL.

[akeller]

@meyerdan @jakobfreund @berndruecker @jwulf thank you all for your input on this topic. In Q3 I'll draft a proposal of ideas as well as have an OKR for implementing incremental improvements.

I'm not looking to provide Windows-specific instructions, rather operating system agnostic ones. Some of the ideas in this proposal may include modifying zbctl for JSON config file support like @jwulf mentioned. This work needs to be scoped and prioritized against other engineering priorities and will inevitably be slower.

When I said internal folks using Windows, I really meant the documentation maintainers (DevX, Advocacy, and mainly Product Engineering). If all our product engineers are using Linux, they won't necessarily be in a mindset to determine what is unfriendly to Windows. So while @berndruecker and @jakobfreund have Windows systems, would you both be volunteering for ongoing maintenance testing? Or do we need to ensure a subset of the documentation maintainers have access to a Windows device or VM?

There will be some low(er) hanging fruit options as well as some more involved ones. Please keep in mind I was an enterprise developer with a pretty hardcore IT security policy. While I could download Node or NPM, I'm not sure I would have been able to download WSL. This is a great question for a developer survey 😄

[jakobfreund]

Thanks @akeller totally see the challenge of us needing to put ourselves in our audience shows, it's a typical challenge for any software company (our Cawemo and Optimize users are quite different from our product engineers too). Although I'd say that this is pretty much what our DevRel practice is about. If we're unsure about the amount of Windows users in our target audience (or how comfortable / able they are to use WSL) we might want to ask that question in our next customer / developer survey (as you suggested) or talk to our Consulting unit (like Ferby) to get a feel for it / validate the feeling you got from @berndruecker , @meyerdan and myself.

Re your question: While I am certainly ready and happy to try out anything you come up with and give feedback, it's not realistic to expect this in an ongoing fashion. Perhaps its different for @berndruecker though.

This work needs to be scoped and prioritized against other engineering priorities and will inevitably be slower.

Absolutely. To me this correlates with the prominence we want to give zbctl in the onboarding experience. Right now it's quite prominent, but that's not inevitable. We could provide a different getting started tutorial that doesn't involve zbctl at all, and as soon as we do that the issue becomes much smaller.

[berndruecker]

While I could definitively try out something occasionally - I would prefer not to commit to ongoing maintenance testing. But if there is no alternative I could offer doing this as interim - better than not having that kind of tests :-)

[akeller]

Closing this out - we will include Windows-specific instructions for Camunda 8 Run (if necessary)