Lesson 6 of 6
Write your platform recommendation
Use the sections you have written to produce a short recommendation for a team deciding whether to adopt an internal developer platform.
4 minPlatform Engineering
After this lesson, you will be able to write a short recommendation for a team deciding whether to adopt an internal developer platform. You will bring together the problem statement, definition, components, benefits, and risks from the earlier lessons into a clear, reasoned conclusion.
Gather your material
You have already written five sections: a problem statement, a definition and comparison, a list of components, a benefits section, and a risks section. In this lesson, you will turn those sections into a recommendation. A recommendation is a short document that says what a team should do and why. It is written for a decision maker, such as an engineering manager or a head of platform.
Start by reading your five sections again. Check that each one is clear on its own. The recommendation will refer to them, so the reader must be able to follow your reasoning.
Structure the recommendation
A good recommendation has four parts: a summary, the main reasons, the main risks, and a clear next step. Keep the whole document to one page if you can. Decision makers often read only the summary and the next step.
The summary is two or three sentences. It states the team's situation, the option you recommend, and the main reason. For example:
"The team is slowed down by manual deployment steps and a mix of tools. I recommend building a small internal developer platform, starting with application templates and a standard deployment pipeline. This will reduce repeated work and make releases more consistent."
The main reasons come from your benefits section. Pick the two or three benefits that matter most for this team. Write each one as a short paragraph. Link each benefit to a problem from your problem statement. For example:
"Today, every new service is set up by hand, which takes about two days. An application template would reduce that to a few hours and make the setup repeatable."
The main risks come from your risks section. Do not list every risk. Pick the two that could stop the team from succeeding, and say how the team can manage them. For example:
"Building a platform takes time away from product work. We can limit this by starting with one small part and only expanding if it proves useful."
The next step is one sentence that says what to do first. It should be small and concrete. For example:
"I recommend that we spend two weeks building a prototype application template and try it with one team."
Write the recommendation
Now write your own recommendation. Use your sections from the earlier lessons. Do not copy the examples above word for word; adapt them to your team's situation.
Keep these points in mind:
- Write in plain English. Short sentences are easier to read.
- Use the names of the tools and processes from your earlier sections, so the reader can see the connection.
- Be honest about the risks. A recommendation that ignores risks is less trusted.
- End with a clear next step. If the next step is vague, the decision maker may not act.
Review your recommendation
Read your recommendation aloud. Check that each sentence adds something. Remove any sentence that repeats an earlier one. Check that the summary matches the rest of the document. If the summary says "build" but the next step says "buy", fix one of them.
Ask a colleague to read it. They should be able to tell you what you recommend and why, after one reading. If they cannot, the recommendation needs to be clearer.
Example recommendation
Here is a complete example for a small team that has already written the five sections. Use it as a model, not as a template to copy.
"Summary: Our team spends a lot of time on manual setup and deployment. I recommend building a small internal developer platform, starting with application templates and a standard pipeline. This will reduce repeated work and make releases more consistent.
Reasons: Today, every new service is set up by hand, which takes about two days. An application template would reduce that to a few hours. Our deployment process has many manual steps, and mistakes are common. A standard pipeline would remove most of those steps and make failures easier to spot.
Risks: Building a platform takes time away from product work. We can limit this by starting with one small part and only expanding if it proves useful. There is also a risk that the platform becomes a bottleneck if only one person maintains it. We will avoid this by having at least two people work on it from the start.
Next step: I recommend that we spend two weeks building a prototype application template and try it with one team."
Key takeaways
- A recommendation has four parts: summary, main reasons, main risks, and a clear next step.
- Pick only the benefits and risks that matter most for the team you are writing for.
- Link each benefit to a problem from your problem statement.
- End with a small, concrete next step that the team can start on soon.
- Review the recommendation to make sure the summary, reasons, risks, and next step all point the same way.
Try it
Write a recommendation for a team you know, or invent a small team with a realistic problem. Use the four-part structure from this lesson. Keep it to one page. Then read it and check: does the summary match the next step? Are the reasons linked to problems? Are the risks manageable? Ask someone else to read it and tell you what you recommend and why. If they cannot, revise it until they can.
Official documentation
Written with AI and checked automatically. Tools change, so a command may behave differently in the version you install. Spotted a mistake? Tell us.