InnerSource Developer Portals

InnerSource Commons Spring Summit 2019
Speakers: Kristof Van Tomme, Pronovix and Daniel Izquierdo, Bitergia

Abstract: During the last InnerSource Commons and Patterns sessions, there have been a set of issues raised by the community. Those are related to the discoverability, findability, awareness, documentation, and others. In this talk, Kristof Van Tomme and Daniel Izquierdo will discuss the use of a Developer Portal as a way to centralize and deal with all of these related patterns. After the introduction we will split out into discussion groups to work on key patterns that the audience believes need to be included in most innersourcing portals.

Transcript

1. (Innersource) Developer portals Kristof Van Tomme / Daniel Izquierdo Cortázar co-Founder/CEO co-Founder/CDO Pronovix Bitergia 1 @kvantomme / @dizquierdo kristof@pronovix.com / dizquierdo@bitergia.com
2. 2 The only consultancy in the world dedicated to devportal development?
3. 3 DISTILL, SHARE, & RESEARCH DEVELOPER PORTAL BEST PRACTICES http:/ /bit.ly/devportals
4. 4 DEVPORTAL AWARDS: GALA EVENT IN NOVEMBER, IN LONDON
5. API THE DOCS: CHICAGO APRIL 8 5
6. WORKING ON A DRUPAL 8 CMS DEVELOPER PORTAL 6 6
7. 7 Software development analytics for your peace of mind
8. GrimoireLab Project 8 100% open source! https://chaoss.github.io/grimoirelab/
9. 9 Bitergia Analytics Services Performance Indicators and KPIs, +60 dashboards covered
10. 10 Bitergia Analytics Services Collaboration network across BUs
11. 11 Bitergia Analytics Services
12. CHAOSSCON: BRUSSELS & SAN DIEGO 12 Pronovix confidential and proprietary
13. 0. How we started thinking about this presentation? 13 Pronovix confidential and proprietary
14. 1. What is a pattern? 14 Pronovix confidential and proprietary
15. A level of abstraction showing a proven solution to a problem with a context A PATTERN IS... 15
16. 16 Problem Problem: Short description. This describes what the issues and challenges are. Context Resulting Context Solution Forces
17. 17 Problem Context: What are the pre-conditions of this problem? This is unchangeable before the solution goes into place. Context Resulting Context Solution Forces
18. 18 Problem Forces: What makes the problem difficult? These are the constraints that can be changed at a cost. Context Resulting Context Solution Forces
19. 19 Problem Solution: Verified or potential solutions to the problem. This solution will change some of the forces. Context Resulting Context Solution Forces
20. 20 Problem Resulting Context: Situation after the problem is solved. Context Resulting Context Solution Forces
21. 2. What are key InnerSource patterns? 21 Pronovix confidential and proprietary
22. • Discover Your InnerSource project ◦ Not looking for stuff internally, ◦ Don’t bother looking, ◦ Find it inside. • Improve Findability, ◦ Badly Named Piles, ◦ Poor Naming Conventions • Common Requirements FINDABILITY AND REUSABILITY 22
23. FOSTER COLLABORATION • The Gig Marketplace • Start as Experiment • InnerSource Portal 23
24. METRICS & ORGANIZATION • Introducing metrics in InnerSource • Review Committee • Contracted Contributor 24
25. 3. What is a developer portal? 25
26. 26 DEVELOPER PORTALS ARE MORE THAN REFERENCE DOCS
27. 27 DEV PORTALS ARE A SELF-SERVICE HUB FOR YOUR DEVELOPERS
28. 28 ...AND AN INTERFACE FOR YOUR INNERSOURCE INITIATIVE
29. 29 YOUR DEV PORTAL ALSO PLAYS A KEY ROLE AS A TRUST SIGNAL
30. 30 4. Pattern: Developer experience
31. 1 Developer friction 31 Developer eXperience =
32. Downstream Developer Journey 32 1. Discover/Research 2. Evaluate 3. Get started 4. Develop & Troubleshoot 5. Celebrate 6. Maintain
33. Upstream Developer Journey 33 1. Engage 2. Catalogue 3. Design 4. Implement 5. QA & Publish 6. Feedback & Support
34. 34 5. Pattern developer docs
35. What docs do you need (1/2)? 35 35 Blog Landing pages Getting started Guides Conceptual docs Reference docs
36. What docs do you need (2/2)? 36 36 Fast API keys Policies Pricing Support SDKs ?
37. QUESTIONS YOUR DEVELOPER PORTAL NEEDS TO ANSWER • What is this? - Landing pages • How do I get started? - Tutorials • What do I need to understand? - Conceptual docs • How do I get X done? - Guides • Do I know all the details? - Reference • Is somebody still working on this API? - Blog • How do I get access? - API key generator • Can I trust this? - API policies • Can I afford this? - Pricing • How can I reach you? - Support contact details • How do I use your API in Y? - SDKs 37
38. 6. Pattern personas 38 Pronovix confidential and proprietary
39. Who are you serving? 39 39
40. How to address different audiences 40 1. Role Based Access Control 2. Information architecture workshop a. Persona research b. User journeys 3. Different types of content.
41. 7. Pattern Docs as Code 41
42. How will you author content? 42
43. How we help customers author content 43 1. 3 types of content: a. Landing pages (responsive design) b. API specification (OAS/Swagger) c. Other documentation (Markdown) 2. Docs as Code - b & c in code repo
44. 6. Pattern Documentation life cycle 44
45. How do you keep docs up to date? 45
46. How enable your colleagues to author and update content 46 1. Documentation services a. Own team b. Through partnership 2. DocOps - CI/CD for docs a. Automated testing b. branching c. Automated deployments
47. 7. Pattern Self service 47
48. How do you enable developers? 48
49. How to enable self service & accelerate development 49 1. Integrate with a. Authentication services (e.g. Forgerock) b. Single sign on infrastructure c. Other services 2. Build development scaffolds 3. Best practices for development paradigm X
50. 8. Pattern Discoverability 50
51. How do you find existing APIs? 51
52. How to improve discoverability 52 1. Faceted search and adapted UX 2. Rich metadata a. Data domain b. Functional domain c. Organisation 3. Progressively enhance software project entities in Workflows
53. 9. Pattern life cycle & consistency 53
54. 54 What is your governance process?
55. 55 How to implement governance processes with a small “g" 1. Life cycle Workflow 2. Upstream documentation 3. Collaborative governance setting 4. Fractal governance
56. 10. Pattern: metrics strategy 56 Pronovix confidential and proprietary
57. How do you measure success? Why metrics? 57
58. 58 Why 1. InnerSource effort justification 2. New InnerSource policies based on facts (not on perceptions or opinions) 3. Tracking evolution of the initiative (awareness -> leading a change -> motivational actions) 4. Team level metrics useful for performance
59. 59 The only consultancy in the world dedicated to devportal development? Pronovix confidential and proprietary