#1 Designing Teams · CI vs CD · Technical Writing
Designing a Team
I’m creating a new team, a 💫 Software Architecture Team 💫. Now “software architecture” is a fancy sounding and abstract area of software development. People like to hold that title and enjoy to command authority that comes with it. Some people hide behind the title and don’t do much of anything. So I make it a point to not have a dedicated full-time-architecture-only team. Instead I want to build a team that is made up by the individuals that already “do architecture” - the tech leads, the engineering managers, the senior engineers etc.. Those who design our systems and ensure we execute on that design, a lot of the time by implementing the design themselves.
Creating such a virtual team is different from creating a new development team (which is not an easy task) - so I found myself in the realm of … I’m not sure if the terminology is right but I call it organizational design: Defining the mission, objectives, activities, processes, feedback loops and success metrics of the team. A team that operates horizontally, across our existing development teams. To be perfectly honest: I don’t know anything about organizational design - but that’s no reason not to try 😁
The key activities in my (preliminary) design:
Bi-weekly Meetings (as in every other week): share/teach “general” architectural topics and dissect an architectural challenge one of our team faces.
Content Creation: Curate & extract re-usable insights and documents for the team (and the future).
“Consulting”: Conduct reviews or short term architecture support on projects.
All of this aims to (1) share practical skills that already exists within our teams across the whole organization (2) without disrupting the important development work of all team members on their projects.
To be honest: It’s seems a bit basic (and there’s more detail and rationale to it which I omitted hre) - but that’s where I’m at right now. I mean basic isn’t necessarily bad, right? What do you think?
It’s an interesting exercise to design an organization. My mind is governed by software design principles, so naturally my thoughts are similar to those during design or code review: What activities can we remove and still be impactful/functional? What is the single responsibility of this activity/feedback loop/process? How can I make the purpose and value more explicit? What are the trade-offs? Where is the business value? Can we find a better name for this activity/process? … etc.
CI, CD, CI/CD… wait what?
Working as software architect I is see many software development teams, each team has its own view on the world of software. One point of confusion that I see time and time again is around Continuous Integration (CI) and Continuous Delivery (CD). I’m surprised by the confusion because the first sentence on Martin Fowler’s Bliki capture the nature of both so clearly:
Continuous Integration is a software development practice where members of a team integrate their work frequently [..].
Continuous Delivery is a software development discipline where you build software in such a way that the software can be released to production at any time.
Let me call out several aspects:
#1 There’s no “Jenkins” in there. People often confuse the tools with the practice of CI and CD.
#2 CI is all about day-to-day collaborative development in a team - integrating code changes. None of this necessitates delivery. You can do this without a CI tool - but that’s driving without the seat-belt on or going for groceries without a mask (in covid times).
#3 CD is all about releasing to production. At this point you want to be done with code is formatting, static analysis, unit testing etc. (this should be covered by CI). In CD you want to focus on… well deploying your application.
The distinction is really clear cut:
CI deals with development concerns.
CD deals with deployment concerns.
CI precedes CD, the output of CI is one of the inputs of CD.
So for example:
Spring web app:
CI = test, lint & assemble into a standalone fat jar
CD = put the jar into a container image, deploy that to k8s (DEV/STG/PROD)
Native mobile app:
CI = test, lint & assemble into an apk/ipa
CD = upload that app binary to AppCenter (DEV/STG) or AppStore/GooglePlay (BETA/PROD)
Am I oversimplifying this? Or why is this confusing so many teams?
Technical Writing
In my company there are horizontal development teams that support vertical development teams. The horizontals build libraries, services and tools for the verticals. This organizational structure isn’t new (at least 5 years), so I’m sad to report that the technical writing skill is not where I want it to be. I mentioned this in a previous blog post:
[At the moment] Rakuten would not be able to do [transition to fully service oriented teams like Amazon did in the early oughts]. Our technical writing literacy is just not there yet.
I guess it’s not that surprising, technical writing (or any writing) is not taught in computer science courses. Similarly I don’t see it as a requirement in job descriptions as a requirement very often (to qualify: I mainly see Rakuten job descriptions). But the reality is that good writing can make or break your service, library or tool. Development teams will pick the best tool for the job (unless you have a monopoly on your niche). If there’s a comparable library/service/tool that does the job and has better documentation - then you just lost a customer. Square’s open source libraries are so popular in the Android ecosystem because they have good writing - in API design and in documentation.
Google released 2 tech writing courses last year, they are a good starting point. But there’s more to it. I’m thinking of running a technical writing training in Rakuten. There’s really no excuse for neglecting that weakness in our organization. Does your company focus on technical writing or invest in training staff in it?
That’s It!
…for this week. Click the button if you want to how this continues! Or don’t. 🤷♀️ Either way, have a great week!