An Internal Developer Portal (IDP) promotes best practices by showing patterns and documentation so that developers can find and follow the steps to build and deploy applications easily.
Speaker: Jon Scheele, Founder & CEO @ Blue Connector, Organiser @ Platform Engineers Singapore and apidays Singapore,
[ Ссылка ]
Presented at Platform Engineers Singapore meetup group on 19 October 2022.
For more information at [ Ссылка ]
When a new developer or engineer comes onto your team, you have this problem or how you transfer knowledge to them so they become productive as soon as possible. I will share about knowledge sharing and documentation, and how you can accelerate this with an internal developer portal. Some of this is inspired by a book I've called "Software Engineering at Google", which has chapters on both knowledge sharing and documentation. For the internal developer portal, I'm going to introduce you to a tool called Backstage.
Firstly, knowledge sharing: Why do we have challenges with learning new things, in particular all things we need to know about what is going on in an organization? One reason is that people don't want to ask questions that appear foolish, they don't want to take a risk, because they may make a mistake and get blamed for something going wrong. Knowledge also exists in pockets across an organization. You have people who have developed expertise over a long period of time, but new people coming on board don't know where to find knowledge or the people who have it. This fragmentation leads to duplication of information. Experts can become the go to person for a given subject, but others may get comfortable in always being able to ask the expert, so they don't bother to learn themselves. So you get these situations where somebody either knows a lot about something or they know very little.
Knowledge takes different forms. It can be personalized one-on-one, which is the most powerful, but doesn't scale very well. Documenting that knowledge is scalable, but it tends to be general, not specific to a particular person's problem. Then there's the tribal knowledge, which is those things that aren't written down, but generally known across the across the team.
You can scale your knowledge with group chats, mailing lists, a Q&A platform (like Stack Overflow), but it can be hard to manage that information or to find information that you're specifically looking for. Sometimes the issue is just so complicated, that you need to find an expert to explain it to you. And that's where they're less scalable things like office hours and tech talks and can come in.
Documentation should explain not just how something works, but why certain decisions were made. The person who designed that system had to make some trade-offs. Do these still apply?
There are several benefits of good documentation:
1. The simple act of writing something down helps you to clarify thoughts in your mind as to how it can work.
2. It provides a record of what works and what doesn't.
3. It makes you look more professional.
4. If your documentation looks good, then people will look at that and say, "Oh, that's a good system, I'm going to use that".
5. It can reduce the amount of questions you get asked about your code.
So you should put as much effort into your documentation as you do into the code.
A developer portal benefits several roles:
1. Engineering managers: they're really keen on maintaining standards across the organization, so if somebody has figured out the best practice, they want to be able to have the entire team follow that best practice and not a multitude of different ways.
2. Developers: it should help you to create a new environment that incorporates all those best practices easily.
3. Platform engineers: want to know where everything is, and make sure that they can bring in new tools and incorporate them into the whole platform.
Backstage ([ Ссылка ]) as a developer portal has become popular is because it incorporates not just static documents, but also gives that view into how you can create a new environment. It was developed by Spotify, then open sourced, and is now under the Cloud Native Computing Foundation. It contains:
1. A software catalog, listing all your all your API's micro services, models, and so on.
2. Templates for how you can create a new instance of an application. If you're building a node.js project, and the organization you're with wants things done a certain way, with certain components to it, and certain styles, you can encourage that by creating a template that people can use to replicate environments.
3. Documents
4. Plugins: Backstage can be extended with plugins for new components that the people who built Backstage didn't think of.
Switch to demo...
