-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.xml
More file actions
163 lines (154 loc) · 19.5 KB
/
index.xml
File metadata and controls
163 lines (154 loc) · 19.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>Praneeth Patakota</title>
<link>https://praneethr86.github.io/</link>
<description>Praneeth Patakota</description>
<generator>Hugo -- gohugo.io</generator>
<language>en-us</language>
<lastBuildDate>Mon, 21 Aug 2023 00:00:00 +0000</lastBuildDate>
<atom:link href="https://praneethr86.github.io/index.xml" rel="self" type="application/rss+xml" />
<item>
<title>The Documentation Conundrum</title>
<link>https://praneethr86.github.io/post/the-documentation-conundrum/</link>
<pubDate>Mon, 21 Aug 2023 00:00:00 +0000</pubDate>
<guid>https://praneethr86.github.io/post/the-documentation-conundrum/</guid>
<description><h1 id="the-documentation-conundrum" >The Documentation Conundrum
<span>
<a href="#the-documentation-conundrum">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h1><p>Any typical code base, given enough years, becomes large enough to find it difficult to maintain documentation for. Every new piece of code I saw in my career had one of the below 3 issues with regards to documentation :</p>
<ol>
<li>No Documentation</li>
<li>Incomplete Documentation or</li>
<li>Outdated Documentation</li>
</ol>
<p>So I started on a quest to find out what&rsquo;s the best way to document your application and the internal implementation, and I shall try to summarise my findings to the best of my knowledge.</p>
<h2 id="tests-are-the-best-form-of-documentation" >Tests are the best form of Documentation
<span>
<a href="#tests-are-the-best-form-of-documentation">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>One wise programmer once told that you won&rsquo;t need any documentation if your tests are perfect. Well, he was right. But for that to happen you need to follow TDD (Test Driven Development) - where you first write a test, then fail it, then write code to pass that test - and iterate until your implementation is ready.</p>
<p>Whoever does TDD well, has the perfect little suite of tests sitting right inside their code base, telling a clear story which no other document can explain.</p>
<h2 id="coding-conventions-make-life-easier-for-everyone" >Coding Conventions make life easier for everyone
<span>
<a href="#coding-conventions-make-life-easier-for-everyone">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>I don&rsquo;t need to stress much on this subject, as it&rsquo;s a familiar topic to you all. Naming Conventions, Comments, Class/Method descriptions and many more rules that we set for ourselves, if followed, also ensure we can have great documentation.</p>
<p>In fact you can use libraries/frameworks like java-docs, Sphinx etc to generate docs directly from code.</p>
<h2 id="wiki-pages-are-outdated-unless-you-enforce" >Wiki pages are outdated unless you enforce
<span>
<a href="#wiki-pages-are-outdated-unless-you-enforce">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>Domain documentation is a tough problem to solve, and there is a good chance that whatever path we take, it eventually grows outdated as it can&rsquo;t keep up with the changes being pushed in by the team. Wiki pages make sense at a HLD/LLD level, and to keep them updated as design gets updated during development, but beyond that, using it as a repository of all documentation possible - is not a smart solution in my opinion.</p>
<h2 id="please-use-readme-md-and-api-docs-well" >Please use README .md and API Docs well
<span>
<a href="#please-use-readme-md-and-api-docs-well">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>The best documentation is not something that sits outside your repo (like a wiki/confluence) but something that can be found right when the developers open up the repository or clone it.</p>
<p>What better place than to use the markdown documentation to ensure at least application level docs are updated there on a regular basis.</p>
<h2 id="versioning-change-log-matters" >Versioning (Change Log) matters
<span>
<a href="#versioning-change-log-matters">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>This is something I saw being followed very well in open-source repositories and it&rsquo;s clearly a useful history of the changes that went in. It wouldn&rsquo;t classify as official docs any day, but it&rsquo;s a really useful addendum to the documentation if you ever want to figure out recent changes that went into application code.</p>
<h2 id="docs-as-websites" >Docs as websites
<span>
<a href="#docs-as-websites">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>Docusaurus, Gatsby and other static side generators work really well. I am still experimenting with them, but my take is that they are good for external facing documentation, Public APIs etc. but for internal documentation, it might get really tough to ask the team to keep the docs updated along with the rapid pace of changes flowing in every day.</p>
<p>There is clearly no silver bullet to fix the documentation conundrum, but a situational approach to decide where to host the documentation for an application, tech stack, domain, or a simple change - can make life much easier for future generations of developers who will probably applaud you for doing a good job at maintaining docs.
If you have any better suggestions, please leave a comment or respond to me via email.</p>
</description>
</item>
<item>
<title>The Art of Holding Back</title>
<link>https://praneethr86.github.io/post/the-art-of-holding-back/</link>
<pubDate>Mon, 14 Aug 2023 00:00:00 +0000</pubDate>
<guid>https://praneethr86.github.io/post/the-art-of-holding-back/</guid>
<description><p>This is the first in a series of mini thought-bytes from my experiences.</p>
<p>There will be a lot of times when your actions will be misinterpreted or your words will be misconstrued in unimaginable ways. It&rsquo;s bound to happen more than once in your career, so what can you do about it ?</p>
<p>The first step is to have an open conversation with whoever raised the concern, and listen, not talk. That itself will make it clear that you have taken the right approach. If you don&rsquo;t listen and react emotionally, it just puts you in the vulnerable position of having to apologize for reacting.</p>
<p>It&rsquo;s always wiser, and there are no exceptions, to be the silent person in the conversation. No matter what the situation, it can be diffused only when one side is silent and listens. The others have no option but to step back and have a thought as well.</p>
<p>The courage to hold back &amp; listen, when all your senses are saying you should react, is a skill to be developed. Most take a life time and never get there. Some try and try and eventually do get there. Which one do you want to be ?</p>
</description>
</item>
<item>
<title>Tech Leadership</title>
<link>https://praneethr86.github.io/post/tech-leadership/</link>
<pubDate>Tue, 08 Aug 2023 00:32:27 +0530</pubDate>
<guid>https://praneethr86.github.io/post/tech-leadership/</guid>
<description><h1 id="notes-on-technical-leadership-and-problem-solving" >Notes on Technical Leadership and Problem Solving
<span>
<a href="#notes-on-technical-leadership-and-problem-solving">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h1><p>Recently I had a deep dive conversation into what the role of a technical leader should be and wanted to share a few points here.</p>
<p>There are lot of aspects to consider here</p>
<h2 id="setting-platform-roadmap-and-vision" >Setting Platform roadmap and vision
<span>
<a href="#setting-platform-roadmap-and-vision">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>Before we can set a roadmap and a vision for where the platform should be heading, it&rsquo;s important to first understand it in-depth. Once you have that level of detailed knowledge about the current system, changes and roadmap can be proposed with a level of certainty in mind.</p>
<p>A technology leader&rsquo;s main goal is to have a constant radar scanning for opportunities and gaps in the system, and propose better alternatives, refactoring, rewrites or even rebuilding the architecture.</p>
<p>Vision is about how all this is going to pan out in the next 5-10 years. If you can get that right, you are the best leader your team can hope for.</p>
<h2 id="encouraging-enforcing-best-practices" >Encouraging (enforcing) best practices
<span>
<a href="#encouraging-enforcing-best-practices">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>Over time, these three things grow beyond a certain level of control - workforce, codebase and business expansion.
All these pose unique challenges, but a common one they all throw at leaders, is the problem if best practices and how to ensure they aren&rsquo;t left out on a daily basis.</p>
<p>If quality, integrity and cost of ownership is taken into consideration, making sure best practices are followed/introduced/revisited etc, is of paramount importance to ensure the health of both your tech stack and your organization. The benefits of this are incomparable if you start listing them down in detail.</p>
<h2 id="technical-debt" >Technical Debt
<span>
<a href="#technical-debt">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>As your code base grows, debt always inevitably piles up, as we make compromises due to urgency of business, lack of stringent reviews for changes and the speed at which we want to deliver in the market today.</p>
<p>The leaders&rsquo; role here is to ensure that debt is not forgotten and take ownership of ensuring it is cleared on a regular basis as part of upcoming changes. There are multiple approaches to this, but I prefer doing it incrementally along with upcoming changes, rather than a big bang hackathon to clear technical debt - that wont bring about any systemic changes for long term.</p>
<h2 id="innovation" >Innovation
<span>
<a href="#innovation">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>Pushing team and oneself towards technical excellence involves keeping an eye out for all opportunities for innovation. Using all avenues possible to push for minor to major innovations helps the leader and their team build their own career paths while also helping their company on their innovation path. It&rsquo;s a true win-win.</p>
<h2 id="being-visible-and-hands-on" >Being visible and hands-on
<span>
<a href="#being-visible-and-hands-on">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>The last but probably the most important item in my opinion, is to be a visible and hands-on leader. A leader has to spend long hours to truly understand about their people, their product, and always be connected to the ground level operations. Losing touch with what your team works on on a daily basis, is like shutting off the gates to learning and development for themselves and the team.</p>
<p>Failing to be hands-on and being available and visible to team and stakeholders, opens up a huge can of worms - lack of trust and respect, lack of knowledge, unable to review team performance and unable to establish an overall growth trajectory for the team. The list goes on.</p>
<h2 id="conclusion" >Conclusion
<span>
<a href="#conclusion">
<svg viewBox="0 0 28 23" height="100%" width="19" xmlns="http://www.w3.org/2000/svg"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" fill="none" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2"/></svg>
</a>
</span>
</h2><p>This is not a complete list, but these are thoughts which got triggered due to a conversation I had and helped me atleast organize these most important categories and start working on them for myself and also for leaders inside my team.</p>
</description>
</item>
</channel>
</rss>