Jekyll2023-09-25T01:26:42-03:00https://www.dewanahmed.com/feed.xmlDewan’s BlogRead about app/data infrastructure, developer advocacy, and my thoughts around a career in tech.Dewan AhmedConnecting the dots: Let’s get ship done!2023-09-25T01:00:00-03:002023-09-25T01:00:00-03:00https://www.dewanahmed.com/joining-harness<p>Today I’m joining Harness as a Principal Developer Advocate. Harness is a complete software delivery platform whose mission is to enable the 30M+ software developers in the world to deliver code to their users reliably, efficiently, securely and quickly. Joining Harness is a significant milestone in my professional career and I’m excited to tell you a bit more in this blog.</p>
<h2 id="from-electrical-engineering-to-tech">From Electrical Engineering to Tech</h2>
<p>Back in 2011, I was a fresh face in Canada, ready with an Electrical Engineering degree, a bunch of research papers under my belt, and some work experience. Little did I know, though, that engineering is a regulated profession in Canada and comes with its fair share of red tape. For many international engineering grads like me, joining the workforce meant going back to school and redoing my entire engineering degree. This was a world away from the “tech” scene, where what you know matters more than any piece of paper.</p>
<p>As an older student trying to make ends meet, I had to juggle three part-time jobs. The only free time I could squeeze out of my crazy schedule was for exams and volunteering at the IEEE student club. Fast forward to 2014, and I stumbled upon an opportunity that felt like a golden ticket. A friend from the Ryerson IEEE student club posted about IBM’s search for Java-savvy interns. While Electrical Engineering programs didn’t offer as many programming courses as Computer Science, I excelled in my Java course.</p>
<p>The school internship was exclusively available for 3rd-year students. So, how did a second-year Electrical Engineering student like me even consider applying to IBM? I was driven by a hunger for success, and I knew I had to create my own path rather than following the conventional route. As the saying goes, “You miss 100% of the shots you don’t take,” and I was determined not to miss this opportunity. I got the job at IBM and this marked the beginning of an amazing eight-year adventure with IBM + Red Hat.</p>
<h2 id="quest-to-find-my-superpowers">Quest to find my superpower(s)</h2>
<p>In 2017, I was a competent developer, but I knew that coding wasn’t my superpower. I enjoyed the part which turned code into software. As I explored more, I started learning docker, Kubernetes, OpenShift, and various CI/CD tools. One key difference-maker was that I chose to learn in public. Over the next three years, I established myself as the go-to DevOps expert on the team. I had many senior IBMers send “thank you” notes for my talks and tutorials that helped them with customer projects. I found one of my superpowers.</p>
<p><img src="/assets/images/2023/ibm-kudos.png" alt="IBM Kudos" /></p>
<p>IBM also had a Toastmasters club, and I eagerly joined to network with fellow IBMers and improve my public speaking skills. While most of my peers dreaded public speaking and writing documentation, I enjoyed doing both and these seemed to come naturally to me. I was about to realize my second superpower.</p>
<p>Around that time, an internal role as a developer advocate opened up at IBM. Reading the job description, I realized that I was doing all those things (and more) in my spare time. I was organizing meetups, writing content, delivering (internal) talks. I just didn’t know that the term “developer advocate” existed and I could get paid for doing the things I love.</p>
<p>“‘Passion’ may be an overused word, but I’ll use it here: the work I do as a developer advocate isn’t just a job; it’s my passion. Working in this role has propelled my career to new heights that wouldn’t have been possible had I remained in Electrical Engineering. In case you’re encountering the term for the first time, I’ve shared my perspective on what it means to be <a href="https://www.dewanahmed.com/why-paying-devrel/#who-is-a-developer-advocate">a developer advocate</a>.</p>
<h2 id="connecting-the-dots">Connecting the dots</h2>
<p>Steve Jobs once said, “You cannot connect the dots looking forward. You can only connect the dots looking backward.” I have a corollary to add here. The dots in your career align better when you have the power of connections. You might ask, “Does luck play a factor here?” Most certainly. We are all familiar with the saying, “The more I practice, the luckier I get.” While grit and hard work are paramount for success, a strong professional network can open numerous doors for you. What may appear as luck is, in reality, the power of connections.</p>
<p>Joining IEEE or Toastmasters clubs wasn’t a part of my job description, but I pursued them anyway in the hope of building new connections. Meaningful connections surpass the value of hard work alone. While you can improve your skills at work, a strong connection can unlock opportunities that hard work alone cannot provide. Over the past 12 years, I’ve actively cultivated meaningful professional relationships, ensuring that when I look back and try to connect the dots, they align more seamlessly.</p>
<h2 id="recognition--stability--title--pay">Recognition > Stability > Title > Pay</h2>
<p>This is my own formula to assess work happiness.</p>
<p>Pay is important to me because I have a mortgage and bills to pay. The grocery store doesn’t accept company values or the vision in exchange for bread. However, I believe that happiness comes from being content, not from chasing more money. Once a certain pay threshold is met, I find happiness in working for a company with the right title, stability, and recognition.</p>
<p>The statement ‘Titles don’t matter’ reflects a position of privilege. As an immigrant who once worked as a retail clerk at Staples for $10.25/hour, I care a lot about my title. My title signifies how a company values my worth and directly affects my career progression. A wrong title can limit my career possibilities and hinder my earning potential. That’s why I prioritize titles over pay.</p>
<p>Imagine receiving an offer to join a company with double the pay and a higher title. However, the company closes its doors in a few months, or there’s a sudden change in priorities, leading to the entire DevRel team being let go. What good is the pay increase or title in such a situation? I prefer career stability over a title and pay bump. Coming to work with the constant fear of the next sudden all-hands meeting, where you might be let go, is a terrible feeling, and it hampers one’s ability to perform at their best. This is why I value stability over title and pay.</p>
<p><img src="/assets/images/2023/mithun-kudos.png" alt="Red Hat Kudos" /></p>
<p>Mithun was my second-line manager at Red Hat. Both my then-manager, Jay Dobies, and Mithun made me feel celebrated at work. There’s a saying that goes, ‘Work where you’re celebrated, not tolerated.’ You may have heard of test-driven development, but recognition-driven development is the best kind. Recognition > Stability > Title > Pay because being recognized by management gives me the confidence and mental boost to engage in more meaningful work. The opposite is also true. An important note is by “recognition”, I’m referring to public praise and appreciation, not necessarily to promotions or pay raises.</p>
<h2 id="why-harness">Why Harness</h2>
<p>I set a very high bar when assessing my next employer. While most candidates focus on preparing for interviews, they often forget that interviews are a two-way street. I interviewed Harness, as a company, the same way they interviewed me. I may be biased, but I can confidently say that Harness passed my assessment with flying colors. Here are the seven steps in my interview process for evaluating Harness:</p>
<h3 id="1-the-offer">1. The offer:</h3>
<p>This is the most basic test. Do they satisfy my minimum required title/pay/PTO requirement? I received a strong offer from Harness so this part was a ✅.</p>
<h3 id="2-product-candidate-fit">2. Product-Candidate-Fit:</h3>
<p>If you were to ask my former colleagues what I’m known for, you’d likely hear keywords like DevOps, CI/CD, GitOps, Tekton, Argo CD, and Kubernetes. I can create content at both 101 and 201 levels for most technologies, but DevOps and CI/CD are my forte. I can delve deep into these topics, so when I was considering my next employer, I sought a company whose main focus was on technologies I excel at.</p>
<h3 id="3-excitement-factor">3. Excitement Factor:</h3>
<p>Developer advocacy is a unique role that requires genuine belief in the product to effectively evangelize it. That’s why I tried and tested the Harness platform to see if it genuinely excited me. From robust documentation to user-friendliness and enterprise readiness, I could envision myself helping developers tackle software delivery challenges using the Harness platform. If you haven’t tried Harness yet, I encourage you to <a href="https://app.harness.io/auth/#/signup/?module=cd&utm_source=dewan&utm_medium=dewan-ahmed-blog&utm_campaign=cd-devrel&utm_content=joining-harness">sign up for free</a> and see for yourself.</p>
<h3 id="4-the-interview-process">4. The interview process:</h3>
<p>An interview process can provide significant insights into a company. I actively maintain professional connections with recruiters. When I started looking for the next adventure, I reached out to my recruiter friend at Harness. Thanks to the connection and trust we had established in the past, the interview process felt less formal and more authentic. It involved a transparent and efficient assessment of my skills and experience (no leetcode interview 😉). Following the interview process, Harness didn’t present a lowball offer, and I didn’t play negotiation games. The process moved swiftly, and within four weeks, both parties had reached a signed agreement.</p>
<h3 id="5-the-brand-assessment-of-the-company">5. The brand assessment of the company:</h3>
<p>When I put on a company t-shirt and speak in public, my personal brand is attached to the company brand. During the interview process, I conducted some research on Harness. From <a href="https://www.crunchbase.com/organization/harness-512d">crunchbase</a> to <a href="https://www.linkedin.com/company/harnessinc/">LinkedIn</a> to <a href="https://www.harness.io/company/press-and-news">Harness in press</a>, I found out that Harness is on a solid growth trajectory and has a strong brand presence.</p>
<h3 id="6-the-founders">6. The founder(s):</h3>
<p>I’ve long been an admirer of <a href="https://www.linkedin.com/in/jyotibansal/">Jyoti Bansal</a>. Jyoti has a tremendous track record of leading high-growth technology companies. Beyond his business acumen, he is very technical (more than 25 US patents). Highly technical founders have always been a key factor in my decision to join a tech startup. Since we’re discussing the interview, here’s one of Jyoti’s posts that I found inspiring:</p>
<p><img src="/assets/images/2023/jyoti-post.png" alt="Jyoti Post" /></p>
<p>To answer this question, I was most proud of the work I did with Terraform at Aiven. I heard from multiple customers that Aiven Terraform Provider and the related docs were one of the main reasons they chose Aiven. I authored Aiven Terraform Cookbook - a bunch of commonly used Terraform manifests to deploy data services. This cookbook was heavily used by Aiven’s solution architects.</p>
<h3 id="7-the-direct-leadership-and-understanding-of-devrel">7. The direct leadership and understanding of DevRel:</h3>
<p>Recently, I wrote about the <a href="https://www.dewanahmed.com/identity-crisis-devrel/">identity crisis in DevRel</a>. From influencer marketing to sales and everything in between, many companies have misunderstood the role of DevRel. I wanted to ensure that my definition of impactful DevRel work aligned with that of Harness’s leadership. To my pleasant surprise, my direct leadership at Harness not only shared the same understanding of DevRel and its impact as I did but had also read my blogs on developer relations before the interview.</p>
<h2 id="lets-get-ship-done">Let’s Get Ship Done</h2>
<p>There’s a massive market opportunity for solving enterprise software delivery challenges. Traditional CI/CD within a single network for a monolithic app is rarely the solution. Today’s enterprise customers are building within air-gapped environments, automating secret management, and seeking an intelligent delivery pipeline capable of troubleshooting build and deployment failures, identifying and helping resolve security vulnerabilities in real-time, all with a privacy-first approach.</p>
<p>During last week’s {Unscripted} 2023 conference, Harness <a href="https://www.prnewswire.com/news-releases/harness-introduces-four-new-modules-to-enhance-efficiency-collaboration-and-security-across-the-software-delivery-lifecycle-301934922.html">announced</a> the official release of four new product modules on the platform: Harness Code Repository, Harness Internal Developer Portal, Harness Infrastructure as Code Management, and Harness Software Supply Chain Assurance. With these advancements, it’s an exhilarating time to be part of Harness as we push the boundaries of software delivery and elevate the developer experience. I’m beyond excited to return to my DevOps and CI/CD roots and join Harness to GET SHIP DONE!</p>Dewan AhmedToday I’m joining Harness as a Principal Developer Advocate. Harness is a complete software delivery platform whose mission is to enable the 30M+ software developers in the world to deliver code to their users reliably, efficiently, securely and quickly. Joining Harness is a significant milestone in my professional career and I’m excited to tell you a bit more in this blog.Going Beyond ‘Do You Know Of Any Open Positions?’2023-07-11T21:00:00-03:002023-07-11T21:00:00-03:00https://www.dewanahmed.com/do-you-know-of-any-open-positions<blockquote>
<p>I’m looking for a job in $SomeField. Do you know of any open positions?</p>
</blockquote>
<p>I’ve spent countless hours over the last 9 years to help folks start a career in tech. However, every time I receive this question, I can’t help but cringe a bit. In this blog, I will discuss why this seemingly innocent generic question is unhelpful for both the person asking and the one being asked. I’ll share some practical strategies for job seekers to boost their chances of success by making specific requests and engaging meaningfully with their connections.</p>
<h2 id="the-limitations-of-asking-for-open-positions">The Limitations of Asking for Open Positions</h2>
<p>When job seekers reach out to their connections on LinkedIn asking if they know of any open positions in a specific technology or field (often the very first message they send as soon as connected), they overlook several key factors. Firstly, job openings are often posted publicly, and candidates can readily search for them on their own. Secondly, expecting a contact to remember and keep track of multiple job seekers in various fields is neither practical nor scalable. However, there is a third reason why this approach is ineffective: the lack of personalization. When your initial message to someone on LinkedIn is a generic request for help, it hampers the ability to establish meaningful connections. It is crucial to demonstrate genuine interest in the person you are seeking help from. Have you taken the time to read their blog or explore their work? Have you offered a genuine compliment or acknowledgment of their expertise? Building rapport and showing a genuine interest in the individual increases the likelihood of receiving a positive response and fostering a more meaningful connection.</p>
<h2 id="the-power-of-specific-requests">The Power of Specific Requests</h2>
<p>Instead of making a generic inquiry, job seekers can significantly enhance their chances of receiving relevant assistance by being more specific in their requests. By tailoring their outreach and highlighting their needs, candidates can engage their connections more effectively. For instance, rather than asking about open positions, consider the following alternatives:</p>
<ol>
<li>
<p>Requesting a connection for an introduction: If the hiring manager or a decision-maker is a first-degree contact of your connection, it may be beneficial to request an introduction or connection to facilitate your application.</p>
</li>
<li>
<p>Seeking guidance: If you have identified a job opening of interest, ask for insights or advice about the company culture, the team, or any specific information that would help you tailor your application.</p>
</li>
<li>
<p>Resume and LinkedIn review: Requesting a review of your resume or LinkedIn profile is a proactive way to engage your connections. Constructive feedback can significantly improve your chances of standing out in the competitive job market. (Hint: I’ve been offering free resume reviews for the last 9 years and have reviewed over 1000 resumes. <a href="https://www.linkedin.com/in/diahmed/">Connect with me</a> and send a DM for a free resume review.)</p>
</li>
</ol>
<h2 id="proactive-job-search-strategies">Proactive Job Search Strategies</h2>
<p>I always encourage seeking help for your career, but if you can handle things on your own, there’s no need to burden others with unnecessary requests. For instance, if you send me a resume full of typos, it gives the impression that you didn’t even bother to run a quick grammar/spelling check. Similarly, a simple LinkedIn search will show you all the available jobs. So, before reaching out, try taking a proactive approach to your job search. Here are some strategies to consider:</p>
<ul>
<li>
<p>Utilize job search tools: Make use of LinkedIn’s robust job search features to find relevant positions. Narrow down your search by filtering according to location, industry, experience level, and more. Here are some free tools:</p>
<ul>
<li>You can use LinkedIn for job search. For many folks, however, reaching out to contacts directly on LinkedIn works better than simply a LinkedIn Easy-Apply. OTOH, <a href="https://news.ycombinator.com/jobs">HN</a> and <a href="https://wellfound.com/jobs">Wellfound (f.k.a. Angel.co)</a> might have better success rate than LinkedIn jobs.</li>
<li>Google Drive –> New Google Doc –> From template –> Resume will give you a simple resume template for free</li>
<li><a href="https://www.open-resume.com/resume-parser">Resume Parser</a> parse information from a resume PDF</li>
</ul>
</li>
<li>
<p>Network and engage: Actively participate in relevant LinkedIn groups and discussions related to your field of interest. Engage with industry professionals, ask insightful questions, and build meaningful connections. Instead of solely reaching out to connections when job searching, make an effort to engage with them regularly. When you connect with someone, ask them about their work, follow their blogs, and offer your help <strong>before</strong> you ask for help. That person might be running a meetup where you can volunteer or they might be maintaining an open-source project where you can contribute. Even the intent will go a long way. Building rapport ensures that when the time comes to seek help, your requests are more likely to be received positively.</p>
</li>
<li>
<p>Follow companies of interest: Identify companies you would like to work for and follow them on LinkedIn. This allows you to stay updated on their latest news, job postings, and any potential opportunities that arise. Once you see an open role, check who within your network works at that company and then make specific requests about that role. Here’s a template:</p>
</li>
</ul>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Hi [Person2],
This is [Person1], we've spoken a few times on Hacker News and then connected on LinkedIn. I saw that your company has openings for QBasic programmers on the website. Do you know anything about this position? I'm interested in applying and would love a referral or introduction to the hiring manager/team leader if that's possible.
Appreciate your time,
[Person1]
</code></pre></div></div>
<h2 id="dont-take-this-the-wrong-way">Don’t take this the wrong way</h2>
<p>Don’t feel discouraged; seeking help is a natural part of career growth. LinkedIn is a game-changer for job seekers, but it’s crucial to use it wisely. Instead of just asking if someone knows of any open positions, let’s focus on asking for the right kind of help. By refining your requests, being specific, and actively engaging with your connections, you can increase your chances of getting meaningful assistance and rocking your job search.</p>
<p>Remember, building professional relationships takes effort, but it’s totally worth it. So, let’s put in the time and energy to connect genuinely with others. When we approach people with a clear purpose and show real interest in what they do, amazing opportunities can unfold.</p>Dewan AhmedI’m looking for a job in $SomeField. Do you know of any open positions?Identity Crisis - A Tale of DevRel2023-05-25T21:00:00-03:002023-05-25T21:00:00-03:00https://www.dewanahmed.com/identity-crisis-devrel<p>Do you identify yourself as a developer advocate?</p>
<p>Are you confident that your skills are being fully utilized in your current role?</p>
<p>OR,</p>
<p>Do you ever feel like your work requires more skills than what you currently possess?</p>
<p>Developer relations (DevRel, in short), both as a field and for those working within it, is currently facing a significant identity crisis. There is little to no standardization across various aspects of the role, from the type of work being done, to the required competencies, and even to the ideal career ladder. This blog presents a somber view of the identity crisis currently plaguing DevRel. I conclude the blog with one action item YOU can take before irreparable damage is done to the very essence of our field’s identity.</p>
<h2 id="forming-the-identity">Forming the identity</h2>
<p>December 9, 1968.</p>
<p>Douglas Engelbart took to the stage to perform what would become known as the <a href="https://www.youtube.com/watch?v=yJDv-zdhzMY">“Mother of All Demos”</a>. Little did the audience know that they were about to witness a demonstration that would forever change the course of computing history.</p>
<p>Engelbart’s presentation was not just a showcase of his technological innovations, but it was also an invitation for developers to collaborate with him in advancing the field of human-computer interaction. Many credit Engelbart to first plant the seed of technology evangelist. However, <a href="https://en.wikipedia.org/wiki/Guy_Kawasaki">Guy Kawasaki</a> is more widely known to pioneer the role of technology evangelist as the first successful one, promoting the Apple Macintosh in the 1980s through his passionate speeches, demonstrations, and events.</p>
<p>Around 2012-13, companies like EngineYard, Twilio, SendGrid, and New Relic took DevRel to mainstream by investing heavily in their DevRel programs and reaching their developers from a community-first approach. Rather than traditional marketing materials, these companies had engineers presenting technical talks at meetups and conferences.</p>
<h2 id="battling-for-an-identity">Battling for an identity</h2>
<p>Long before I had the title of developer advocate, I was delivering talks, hosting meetups, and writing technical blogs on my own time. I was doing this out of joy and could never imagine that I could do this full-time (and get paid to do so).</p>
<p>As a full-time software engineer doing “DevRel thing” on the side, I didn’t have an identity crisis. I was just another software engineer who was active in writing and public speaking. When I started to do DevRel full-time, I asked myself “how valuable and visible is my work?”. Check out what <a href="https://twitter.com/rachelnabors">Rachel</a> has to say about the value of tech writing:</p>
<p style="text-align:center;"><img src="/assets/images/2023/rachel-tweet-1.png" alt="Value of tech writing" width="400" /></p>
<p>This can be very much relatable to the perceived value of DevRel.</p>
<p style="text-align:center;"><img src="/assets/images/2023/rachel-tweet-2.png" alt="Value of developer advocates" width="400" /></p>
<p>It’s a <a href="https://twitter.com/rachelnabors/status/1647771654519676929?s=20">golden thread</a> for anyone in DevRel. Please bookmark!</p>
<p>When I started my first official DevRel role at IBM, the answer to “what do you do at IBM?” never ended in one line as developer advocacy was new to most folks. I was tired to explain my role every time so I <a href="https://medium.com/@dewanahmed/what-i-do-as-a-developer-advocate-at-ibm-da2252179f6">wrote a blog to explain</a>. If you think that something clever like “I help developers to succeed” or “I educate developers on $someTechnology” would work, please try it out on someone who never heard of developer relations and then ask them back if they understood what you do from that clever one-liner.</p>
<h2 id="how-did-we-arrive-at-this-point">How did we arrive at this point?</h2>
<p>Surprisingly enough… it’s because DevRel became highly successful!</p>
<p>Seeing the massive success of DevRel programs at companies like Twilio and HashiCorp, other companies wanted to replicate.</p>
<p>However, simply copying their models does not guarantee success. In fact, many tech companies that attempted to do so ended up failing in their DevRel programs. Without an insider knowledge, here’s my calculated guess on the “why”:</p>
<ol>
<li>
<p>Lack of genuine commitment: DevRel programs require a genuine commitment to developers and their needs. This means investing in resources like documentation, support channels, and events, as well as taking the time to engage with the developer community. Many companies see DevRel as an afterthought or a checkbox item, rather than a core part of their business strategy.</p>
</li>
<li>
<p>Poor understanding of the developer mindset: Developers have a unique mindset and approach to problem-solving. They value tools that are easy to use, well-documented, and flexible. Companies that fail to understand this mindset may develop tools and resources that are too complex or too restrictive, which can turn developers off. Even the best DevRel team won’t be able to shine a poor product.</p>
</li>
<li>
<p>Lack of trust: Developers are a discerning audience, and they can quickly sniff out inauthenticity. Companies that lack trust with the developer community, perhaps because of a history of closed-source practices or a lack of transparency, may struggle to build meaningful relationships with developers. Imagine that you (a developer advocate) went above and beyond on a developer event. You delivered a talk, spent hours on booth duties, and talked to a bunch of developers about the <strong>technology</strong> behind your product. You write a 9 page trip report with all the details and the CEO comes to you right after the event asking for an ROI. It’s extremely easy to lose the trust of the community as well as the trust of your own DevRel team.</p>
</li>
<li>
<p>Insufficient resources: Building a strong DevRel program requires a significant investment of time, money, and people. Companies that try to cut corners or skimp on resources may find that their DevRel efforts fall short. Sure, you can hire 3 junior folks to form a DevRel team but without senior people in the team to groom them, they’ll burn out fast with trying to do 10 things at a time and battling for an identity.</p>
</li>
<li>
<p>Poor execution: Even with the best intentions and resources, DevRel programs can fail if they are poorly executed. This might include a lack of follow-through on promises, inconsistent messaging, or an inability to respond to developer feedback in a timely manner.</p>
</li>
</ol>
<h2 id="engineering-marketing-product-office-of-cto">Engineering? Marketing? Product? Office of CTO?</h2>
<blockquote>
<p>Oh no! Not “where should DevRel sit” question again 🤬</p>
</blockquote>
<p>An engineer typically works under the Engineering org, while an SDR works in Sales, and a marketing analyst works in Marketing.</p>
<p>But where does a developer advocate fit in? Many of them are engineers by trade, work closely with the product team, (oftentimes) report to the marketing department, and can be great allies for sales reps without directly selling the product.</p>
<p><a href="https://twitter.com/karinwolok">Karin</a> recently asked this same question which received <a href="https://twitter.com/karinwolok/status/1655951362151292931?s=20">31 responses on Twitter</a>. In these responses, people had eight different opinions on where DevRel should sit - from some flavors of “it depends” to “DevRel as a separate org” to “sales”. Out of all 31 responses, I share the same view as <a href="https://twitter.com/jimbobbennett">Jim Bennett</a>:</p>
<blockquote>
<p>It’s such a cross functional org that there is no real right answer. Done well it’s such a strong collaboration across all the orgs that it should have access to marketing budget as well as product teams.</p>
<p>Just not sales - it should never be tied to revenue.</p>
</blockquote>
<p>Had I responded to that thread, here would be my corollary to Jim’s response: Developer relations (DevRel), when done right, acts as a metaphorical glue among cross-functional teams, similar to the <a href="https://traditionalkyoto.com/culture/kintsugi/">Japanese art of Kintsugi</a>. DevRel, like the gold in Kintsugi, repairs fractured relationships or creates non-existing relationships between an organization and its target developer audience. It creates an environment based on authenticity and trust, without a direct purpose of “sell no matter what”.</p>
<p>But is DevRel really a golden solution for everyone?</p>
<p>Does every organization have the capacity to use the power of DevRel?</p>
<h2 id="the-real-cost-of-identity-crisis">The real cost of identity crisis</h2>
<p>Here’s a CEO asking if developer advocacy is a good idea or not.</p>
<p style="text-align:center;"><img src="/assets/images/2023/is-devrel-bad-idea.png" alt="Developer advocates worse than consultants" width="400" /></p>
<p>Here’s a programmer with ~40K Twitter followers who does not trust developer advocates because this person feels that developer advocates are just pitch people for their employers instead of people really helping developers.</p>
<p style="text-align:center;"><img src="/assets/images/2023/unfollow-developer-advocates.png" alt="Unfollow developer advocates" width="400" /></p>
<p>Here’s a company pitting DevRel teams against each other without even taking their consent. They have since taken down the post due to backlash.</p>
<p style="text-align:center;"><img src="/assets/images/2023/devrel-league.png" alt="DevRel league" width="400" /></p>
<p>At the core of this confusion, there are two questions:</p>
<ol>
<li>What is DevRel?</li>
<li><a href="https://www.dewanahmed.com/why-paying-devrel/">Why are we paying them?</a></li>
</ol>
<p>If we (DevRel community) cannot have a unified answer to the first question, more and more people will question the effectiveness of DevRel. I don’t know about you but I’ve seen more than enough “And the entire DevRel team was let go” posts in the last few months. In weak economy, you need a strong justification to the second question to save your job.</p>
<h2 id="have-we-forgotten-how-to-be-engineers">Have we forgotten how to be engineers?</h2>
<p>I live in Canada so I’m aware that the term “engineer” has a special meaning at some places that is regulated by local engineering associations. However, my use of the term “engineer” refers to anyone who has professionaly built software and hence, (software) engineer. This includes a wide variety of roles such as developers, SysAdmins, DBAs, Solution Architects, etc. It has nothing to do with your path to becoming a software engineer. Whether you’re a ComSci PhD or a bootcamp grad, you possess certain skillset that is common to expect from a majority of other software engineers. You know how to use version control, read a piece of code, write and debug code, and so on.</p>
<p>In the last 10 years, the identity of DevRel has become more convoluted. When I started at IBM in 2014, there were very few developer advocates in the industry (compared to now). A developer advocate would be someone with decades (not years) of engineering experience who chose not to go the management or principal engineer route. They wanted to teach and share their experience.</p>
<p>One of the common complaints DevRel folks have is that we don’t get a seat at the table in terms of product development and roadmap. Your peers at product or engineering will likely respect product feedback coming from an engineer than from someone who has very little to do with coding in their day to day job.</p>
<p>Does it mean a developer advocate need to regularly write code that runs in production? No! <strong>Zero coding</strong> and <strong>writing production code daily</strong> are two extremes. At bare minimum, you should be comfortable writing code samples and you should do that regularly as part of your job. “I know how to code and I’ll do it when needed (interpreted as <em>never</em>)” is a dangerous mindset for a developer advocate.</p>
<h2 id="you-arent-gatekeeping-are-you">You aren’t gatekeeping… are you?</h2>
<p>When I express my view on developer advocates needing to be highly technical, I usually get three types of questions/comments:</p>
<ul>
<li>What about developer advocates who are more community focused?</li>
</ul>
<p>My response: A developer advocate is the default role that comes to mind when people think about DevRel. If you’re a series-A startup and can only afford to have one person on your DevRel team, it’s likely that you’ll hire a developer advocate. This is why DevRel and developer advocate are often used interchangeably, even though one is a subset of the other.</p>
<p>Out of the 3Cs (code, content, community), what % of code and technical content are you producing as a developer advocate? If the answer is “zero” or “very little”, you’re confusing developer advocates with community managers. A community manager is a super important role. At smaller companies, a developer advocate might be doing community management on top of their advocacy work. But <strong>code</strong> and <strong>technical content</strong> come first for a developer advocate, with <strong>community</strong> work as a nice-to-have.</p>
<ul>
<li>Are you trying to gatekeep?</li>
</ul>
<p>My response: Not really; I’m simply sharing my opinions on DevRel (on my personal blog). A question back at you: can you maintain quality of anything without setting some level of standards? From a software engineer to a sales rep, there is clear and <strong>unified</strong> job description and expectations for every single role in tech industry; except DevRel! Most of what I’m saying have been said many times in the past by well-respected DevRel leaders.</p>
<ul>
<li>But.. I have empathy for developers. Isn’t that enough?</li>
</ul>
<p>My response: Having empathy is important but empathy <em>alone</em> will not help you become a strong develper advocate. How does one cultivate empathy in the first place? Tim Berglund, a respected figure in DevRel and one of the best developer advocates out there, <a href="https://www.youtube.com/watch?v=9OmURvI9gwo&t=1336s">points out</a> that genuine empathy for developers is challenging to achieve if you have never been a developer yourself. It’s almost impossible to truly understand their experiences and struggles without a background in engineering or coding.</p>
<p>Tim goes on to explain that developers worldwide, regardless of spoken language, share a common dialect and inside jokes that only fellow developers can comprehend. This shared language and understanding of the developer’s world can only be acquired through years spent behind a keyboard, earning a livelihood by writing code. It is by going through similar challenges and experiences that one can truly develop the empathy necessary to connect with other developers.</p>
<h2 id="devrel-is-not-influencer-marketing">DevRel is NOT influencer marketing</h2>
<p>Once I had a recruiter reach out who was looking for a DevRel superstar with a certain Twitter follower count as part of the required skills on the job description. I was about to write this section and then heard Tim Berglund craft the same message perfectly. Listen to what Tim has to say about the influencer path vs. the traditional DevRel path ⤵️</p>
<iframe width="560" height="315" src="https://www.youtube.com/embed/9OmURvI9gwo?clip=Ugkx4WhdkUkyDO8uuj7V8CT5LwYWmg-09hal&clipt=EN_2dxjjuHs&autoplay=0" frameborder="0" allowfullscreen=""></iframe>
<h2 id="youre-a-developer-advocate-whats-next">You’re a developer advocate… what’s next?</h2>
<p>Around 2013-14, some of my IBM colleagues retired as a developer advocate. This is after they became a developer advocate after working as a senior engineer for 20+ years. I wrote before that <a href="https://www.dewanahmed.com/why-paying-devrel/#developer-advocacy---not-an-entry-level-role">developer advocacy is not an entry-level role</a>. In present days, some companies are hiring junior folks as a developer advocate (totally not to save on 💰) and then they are not providing them a DevRel career path to grow.</p>
<p>If you’re a solo developer advocate, what does a promotion look like for you? If you’re manager of a DevRel team, do you have a defined career ladder at your company? At what point in your DevRel career do you reach a plateau, where staying in a DevRel role no longer offers further growth opportunities?</p>
<p>Scanning the internet, I found <a href="https://www.devrel-ladders.com/">four companies</a> with publicly posted DevRel career path. Besides these four companies, I know a few more with defined career ladders for DevRel individual contributor (IC) but none for DevRel managers. From DevRel-ladders site:</p>
<blockquote>
<p>Often one of the hardest challenges in Developer Relations is <strong>clarity</strong>. Clarity around goals, metrics, place within the organization, but most importantly clarity about your career path.</p>
</blockquote>
<p>When your DevRel team doesn’t have clarity, they’ll face an identity crisis and that’s the shortest path to burnout.</p>
<h2 id="but-there-is-hope">But… there is hope</h2>
<p>If you’ve managed to read this far, thank you for your patience! There are three key things YOU can focus on in order to revive the lost identity of developer relations.</p>
<p>If you’re a DevRel IC, focus on:</p>
<ul>
<li>Technical expertise</li>
<li>Authenticity</li>
<li>Optics</li>
</ul>
<p>You, as a developer advocate, need to showcase the technical expertise which is the foundation of helping your developers succeed. You have to do that in an authentic way and not treat every community member as a new lead in the marketing funnel. Besides doing the work, you have to be intentional in conveying the value of your work within your company. This is where the optics comes in.</p>
<p>If you manage a DevRel team, focus on:</p>
<ul>
<li>Exec buy-in</li>
<li>DevRel metrics</li>
<li>Avoiding burn-outs</li>
</ul>
<p>Your exec team must understand the value of developer relations <strong>before</strong> they hire the first developer advocate and they should be transparent in their support for DevRel. If you are in a difficult spot where you have to convince the leadership on DevRel ROI, understand what metrics are important for the exec team and find a direct/semi-direct relation with <a href="https://www.swyx.io/measuring-devrel">DevRel metrics</a>. Most people working in DevRel are eager to help and often find it challenging to say “no”. When this eagerness is coupled with a lack of clarity and clear expectations, it becomes the primary cause of DevRel burnout. It is crucial to prioritize the well-being of your team and foster a sense of psychological safety within the organization.</p>
<p>My hope from this blog is to inspire you, the reader, to revive the lost identity of developer relations and help developers succeed. Remember, DevRel is the only team at your company that can speak the engineer’s language, provide regular feedback to the product team, function as a marketing team, and grow the community as the face of your company.</p>Dewan AhmedDo you identify yourself as a developer advocate?How to install PostgreSQL client psql on macOS, Linux (Ubuntu), and Windows?2023-03-26T21:00:00-03:002023-03-26T21:00:00-03:00https://www.dewanahmed.com/install-psql<p>The installation process for the PostgreSQL client, <strong>psql</strong>, may vary depending on your operating system. Here are the general steps for some popular operating systems:</p>
<h2 id="linux-ubuntu">Linux (Ubuntu)</h2>
<ol>
<li>Open the terminal and run the following command to update the package list:</li>
</ol>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt-get update
</code></pre></div></div>
<ol>
<li>Install the PostgreSQL client by running the following command:</li>
</ol>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt-get install postgresql-client
</code></pre></div></div>
<h2 id="macos">macOS</h2>
<ol>
<li>Install Homebrew by running the following command in Terminal:</li>
</ol>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
</code></pre></div></div>
<ol>
<li>Once Homebrew is installed, run the following command to install PostgreSQL:</li>
</ol>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>brew install postgresql
</code></pre></div></div>
<p>Alternatively, you could also use homebrew to install <strong>libpq</strong> that gives you <strong>psql</strong>, <strong>pg_dump</strong> and a whole bunch of other client utilities.</p>
<p>Unfortunately, since it provides some of the same utilities as are included in the full PostgreSQL package, brew installs it “keg-only” which means it isn’t in the PATH by default.</p>
<h2 id="windows">Windows</h2>
<ol>
<li>Download the PostgreSQL installer for Windows from <a href="https://www.postgresql.org/download/windows/">the official website</a>.</li>
<li>Run the downloaded installer and follow the prompts to install PostgreSQL.</li>
</ol>
<p>After completing the installation process, you should be able to run <strong>psql</strong> in the terminal/command prompt to connect to your PostgreSQL database.</p>Dewan AhmedThe installation process for the PostgreSQL client, psql, may vary depending on your operating system. Here are the general steps for some popular operating systems:MeetUps - an underrated tech job board2023-03-14T21:00:00-03:002023-03-14T21:00:00-03:00https://www.dewanahmed.com/meetups-land-a-tech-job<p>Are you trying to find your first job in IT? Are you trying to switch to a better (paying) tech job? If you have tried to reach out to a professional on LinkedIn for networking, you know that the response rate is often very low. In this blog, I’ll tell you a story of a secret job board that most don’t know of. Rising from the ashes after the pandemic, meetups are the best places to find your next tech job. In this blog, the terms “meetup” and “tech meetup” are used interchangeably.</p>
<h2 id="what-is-this-meetup-story">What is this “meetup story”?</h2>
<p>I’m assuming that you already know what a tech meetup is. In case you don’t, a tech meetup is an event where people from the technology industry gather to share their knowledge, network with each other, and learn from industry experts. For this blog post, I’m not referring to larger conferences with multiple speakers and workshops, rather the smaller and more informal events you see on platforms like “meetup.com”.</p>
<p>Meetups typically, though not always, are located in a particular geographic area, such as Newfoundland Canada or Lagos Nigeria. They also are usually free to attend, and are run by volunteers and supported by sponsors who provide space to meet and other resources.</p>
<p>As a meetup organizer myself and having many meetup organizers as close friends, I know first hand how challenging it is to plan and host a meetup. Besides finding a good venue and sponsors, the main challenge of a meetup organizer is finding speakers and a (decent size) audience for their next event.</p>
<p>If you’re a seasoned tech professional, you can offer to speak at your local meetup. Even if you’re just beginning, you might have a story to tell about your tech journey. If you’re looking to attend the meetup only and not deliver talks, it is equally appreciated by the meetup organizers. The point is, if you express an interest to get involved with a meetup, it’s always music to the ears of meetup organizers.</p>
<p>When trying to find a tech job, it matters <strong>who you know</strong> as well as <strong>what you know</strong>. Keep on reading and I’ll tell you how you can get to know your future manager or colleagues from these meetups.</p>
<h2 id="getting-involved-with-a-meetup">Getting involved with a meetup</h2>
<p>The “meetup game” comes in two modes - <strong>easy</strong> and <strong>extreme</strong>. The <strong>easy</strong> mode is getting involved with an existing meetup. The <strong>extreme</strong> mode is starting your own tech meetup from scratch. Unless there are no meetups in your area, I wouldn’t advise starting a meetup for the sole purpose of networking and finding a tech job, so I won’t discuss starting a meetup further. To find a job, you can totally join an existing meetup in your locality.</p>
<p>There are many ways to find tech meetups in your area. Here are a few tips:</p>
<ul>
<li>
<p>Use Meetup.com: Meetup.com is a popular platform for finding and joining tech meetups in your area. You can search both by technology and location.</p>
</li>
<li>
<p>Attend conferences: Tech conferences are a great place to meet other professionals and learn about new technologies. Many conferences also have associated meetups or networking events.</p>
</li>
<li>
<p>Ask around: Ask colleagues or friends in the industry if they know of any local meetups that might be of interest.</p>
</li>
<li>
<p>Use other local resources: If there’s a local slack or discord, ask there. If there’s a local co-working space or tech accelerator, see if they know of any.</p>
</li>
<li>
<p>Use geographically focused online resources: Ask on HackerNews if anyone knows about local meetups. Search on your city or area’s reddit to see if anyone mentions a meetup.</p>
</li>
<li>
<p>Check social media: Many tech meetups use social media platforms like Twitter and LinkedIn to promote their events and share information.</p>
</li>
</ul>
<h2 id="but-what-about-virtual-meetups">But… What about virtual meetups?</h2>
<p>The essence of tech meetups is in-person networking. The pandemic prompted a flurry of virtual meetups; just as the rest of life went virtual, so did meetups. However, I’ve attended and hosted many of these virtual meetups and they are a far cry from the interactiveness and engagement of in-person meetups. While they are great for learning from presenters, you won’t interact with the other participants that much.</p>
<p>Connecting with tech professionals is valuable regardless of the geography. However, in my humble opinion, the virtual medium makes networking extremely difficult. It’s hard to have casual conversations, difficult to connect, and tough to move between conversations.</p>
<h2 id="whats-in-it-for-me">What’s in it for me?</h2>
<p>Participating in meetups has all kinds of benefits. You can learn from industry experts, network with other professionals, and most meetups provide free food/drinks (the ultimate perk). However, I made you a promise at the beginning of this blog that meetups are underrated job boards and this is the time to explain “how”.</p>
<p>Meetups work slightly differently than traditional job boards. In a traditional job board, hiring managers post jobs and candidates scan the board to find a suitable job. For meetups, candidates “post” themselves by actively participating and other tech professionals add mental notes about these candidates based on the skills they showcase. When there is an immediate need for that skill, I’ve seen hiring managers reach out to the speaker of a meetup immediately after the talk, exchange contacts, conduct a short interview process, and extend job offers. Even if there’s no immediate need, engineering leaders always want to add talented tech professionals in their networks and they reach out as soon as there’s an open job req.</p>
<p>Does it mean that only speakers at meetups get to do networking and potentially secure job offers? Absolutely not! Almost every meetup dedicates time for networking. As a participant, you have to identify tech professionals from your target industry or companies. During the networking session, you can introduce yourself, engage in thoughtful technical discussions, and request them to add you to their LinkedIn network. Your goal is to showcase your skill set. It’s a lot easier when you deliver a talk as you have the platform and all eyes are on you. However, you can also do that by effectively connecting during the networking sessions.</p>
<p>Like any networking effort, meetups don’t usually pay off immediately. You’re extremely unlikely to get a job offer after the first attendance. But, as you build up connections and more and more people know who you are and what you can offer, you’re increasing the odds of matching an open role at a company where you already have someone who can confirm your skills and fit.</p>
<h2 id="making-the-most-out-of-a-meetup">Making the most out of a meetup</h2>
<p>If you’re joining a meetup to find your next tech job, here are my tips:</p>
<ol>
<li>
<p>Be open to learning: Even if you’re an experienced developer, there’s always something new to learn. Don’t let your ego come in the way of learning.</p>
</li>
<li>
<p>Don’t pitch your company or product: People do not spend their evenings getting product pitches. An easy way to never get invited to a meetup (or to not be invited back) is by treating every other meetup attendee as a prospect.</p>
</li>
<li>
<p>Do effective networking: Don’t be afraid to introduce yourself to others and strike up a conversation. But don’t start the conversation with a stranger this way: “are you guys hiring right now?” Effective networking starts with finding a common ground and building a relationship based on that common ground. For tech meetups, that common ground is technology. For example, for a ruby meetup, you might start a discussion on unit testing in ruby. As you connect with professionals and build a relationship, there will be a time to discuss job opportunities. The only time you can start the conversation by asking about open jobs is if you’re at an actual career fair.</p>
</li>
<li>
<p>Follow up: If you meet someone interesting at a tech meetup, be sure to follow up with them after the event to keep the conversation going. The level of follow up depends on the strength of the connection. In increasing order of commitment, might include connecting on LinkedIn, exchanging emails on the topic of discussion, hopping on a phone or video call, or meeting in person for coffee.</p>
</li>
<li>
<p>Consider volunteering: From helping to find sponsors to setting up chairs to ordering food, there are many ways you can volunteer at a meetup. Almost every meetup I know is short-staffed and they appreciate anyone who volunteers. You can volunteer to do pre meetup prep like speaker logistics or can help during the meetup like setting up chairs, breaking them down, carrying food, etc. If I see someone volunteering at my meetup, I make a mental note of their kindness and make an active effort to repay the favor (sometimes that’s connecting them with folks who are hiring :) ).</p>
</li>
</ol>
<hr />
<p>In this blog, I covered a brief overview of meetups, the value they provide, and how you can get involved to help the community as well as take your tech career one step forward. If you ever plan to visit the East coast of Canada, I welcome you to join the <a href="https://www.meetup.com/atlantic-canada-tech-meetup/">Atlantic Canada Tech Meetup</a> for some great talks, solid networking, and delicious food.</p>Dewan AhmedAre you trying to find your first job in IT? Are you trying to switch to a better (paying) tech job? If you have tried to reach out to a professional on LinkedIn for networking, you know that the response rate is often very low. In this blog, I’ll tell you a story of a secret job board that most don’t know of. Rising from the ashes after the pandemic, meetups are the best places to find your next tech job. In this blog, the terms “meetup” and “tech meetup” are used interchangeably.Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code2023-01-09T20:00:00-04:002023-01-09T20:00:00-04:00https://www.dewanahmed.com/markdown-asciidoc-restructuredtext<p>Who writes the developer documentation for your product? During the early days of my tech career, I worked on a database replication product at IBM. My immediate team had developers and testers but not a single technical writer. I can speak for myself when I say that I never bothered to know who keeps writing the lengthy and complex documentation for every release. Since then, many companies in tech (including companies like IBM) have taken a modern approach to documentation. This “modernization” started when more and more developers started writing documentation (not all developers hate writing docs 🤭). Having git running in their DNA, these developers wanted to bring in collaboration, version control, scripting, and easier bug tracking within developer documentation.</p>
<blockquote>
<p>:information_source: Note that I’m not using the term “product documentation”, rather “developer documentation”. If your users are developers, it’s more likely that they would appreciate reading docs written by other developers.</p>
</blockquote>
<p>With the text files for documentation in version control system and changes going through the pull request process, the documentation is treated exactly like software code and hence docs-as-code. I see five stages in docs-as-code implementation:</p>
<ol>
<li>Write: Use a markup language to write the docs.</li>
<li>Extend (optional but almost a requirement): Use a framework to avail features that are not part of the basic markup.</li>
<li>Host: Host the markup files on some repository. This could be self-hosted or a managed provider.</li>
<li>Automate the build (optional but highly recommended): Add a CI with spelling, prose, link checks, etc.</li>
<li>Publish: Deploy your documentation live using platforms like GitHub (Pages), Vercel, or Netlify.</li>
</ol>
<p>In the first part of my docs-as-code series, I’ll talk about the choice of markup languages, the available frameworks, and do a comparison among Markdown (md), Asciidoc (adoc), and reStructuredText (reST) based on some use cases. I’ll skip the history but in case you’re interested, my friend and colleague Tibs delivered a talk on the <a href="https://www.youtube.com/watch?v=P-7hwjocEpM">history of text markup languages</a>. My hope is to provide you with a detailed analysis of these choices of markup languages and frameworks so that you can make an informed decision when selecting one for your next developer documentation project. If you don’t need a brief intro and would like to skip the appetizer, you can go straight to the entrée - <a href="#choose-the-right-markup-and-framework">Choose the right markup</a> section.</p>
<h1 id="the-choices---md-adoc-rest">The choices - md, adoc, reST</h1>
<p>Before choosing a markup language, you’ll need to choose either a desktop code editor like <a href="https://code.visualstudio.com/">VSCode</a> or stay in your terminal and use something like <a href="https://www.vim.org/"><del>Emacs</del>VIM</a>. Most code editors will have plug-ins for popular markup languages which will offer you syntax highlighting, preview, etc. If you’re testing or learning a specific syntax, there are many online editors, such as, <a href="https://stackedit.io/">StackEdit for Markdown</a>.</p>
<p>The main choices for document markup languages are:</p>
<ul>
<li>Markdown (md)</li>
<li>Asciidoc (adoc)</li>
<li>reStructuredText (reST)</li>
</ul>
<h2 id="markdown-md">Markdown (md)</h2>
<p>The <a href="https://daringfireball.net/projects/markdown/">original version</a> of Markdown by John Gruber doesn’t specify the syntax unambiguously. For example, it doesn’t have table formatting. Due to the popularity of Markdown and the limitations of Gruber Markdown, a plethora of variations, or “flavors”, of Markdown have been introduced. Due to this lack of standard, folks like <a href="https://twitter.com/ericholscher">Eric Holscher</a>, who are passionate about the community, have been vocal about <a href="https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/">not using markdown for documentation</a>.</p>
<p>In 2014, a group of Markdown fans came together and established <a href="https://commonmark.org/">CommonMark</a> - a standard, interoperable and testable version of Markdown. In March 2017, GitHub published a formal spec for GitHub-Flavored Markdown (GFM); based on CommonMark. In the <a href="https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/">accompanying blog post</a> when releasing GFM, GitHub addressed many of the limitations that Eric Holscher raised, things like how many spaces are needed to indent a line, or how many empty lines you need to break between different elements. GFM is, by far, the most popular flavor of Markdown.</p>
<p>If you’re just starting out with Markdown, check out the <a href="https://www.markdownguide.org/basic-syntax/">syntax</a> and write some hello-world docs <a href="https://markdownlivepreview.com/">online</a>.</p>
<p>For Markdown, there are <a href="https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors">A LOT</a> of flavors. Despite all eleventy-zillion flavors, Markdown is loved for developer documentation due to its simplicity.</p>
<h2 id="asciidoc-adoc">Asciidoc (adoc)</h2>
<p>You started with Markdown, but then you needed to embed a YouTube video. So you embed HTML within your Markdown doc. As your project grows, there will be more HTML and some JavaScript embedded in your Markdown files. With out-of-the-box features like tables, admonitions (tips, notes, warnings, etc.), and table of contents, Asciidoc is a popular choice for documentation projects that want to avoid gluing HTML and JavaScript for advanced use. Asciidoc has no flavors so there’s really just a single standard. You might have heard about GitHub Flavored Asciidoc (GFA). This is not a flavor per se, rather GitHub using Asciidoctor in safe mode to render files with the extension <code class="language-plaintext highlighter-rouge">.adoc</code>, <code class="language-plaintext highlighter-rouge">.ad</code>, and <code class="language-plaintext highlighter-rouge">.asciidoc</code>. More on Asciidoctor under the <a href="#framework-framework-framework">framework section</a>. <a href="https://asciidoclive.com/">asciidocLIVE</a> is a great place to start if you’re testing waters with Asciidoc and would like to learn the syntax.</p>
<h2 id="restructuredtext-rest">reStructuredText (reST)</h2>
<p>If you’re in the Python community, you might be using reStructuredText for documentation. A popular site that uses this markup language is <a href="https://www.writethedocs.org/">WriteTheDocs</a>. The reStructuredText parser is a component of <a href="https://docutils.sourceforge.io/index.html">Docutils</a> and is the default markup language used by <a href="https://www.sphinx-doc.org/en/master/index.html">Sphinx</a>. reStructuredText can be extended using <a href="http://docutils.sourceforge.net/docs/ref/reST/directives.html">custom directives</a> that can satisfy a wide variety of documentation needs. <a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">Here</a> is a quick primer on reStructuredText if you’re getting started. You can play with the reStructuredText syntax using <a href="https://livesphinx.herokuapp.com/">this online editor</a>.</p>
<p>reStructuredText offers a number of useful <a href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">directives</a> out-of-the-box. For example, admonitions (“safety messages” or “hazard statements”) can appear in reST like this:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>.. DANGER::
Do not review/merge your own PR!
</code></pre></div></div>
<p>You can also use <a href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar">sidebar</a>, <a href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#math">math</a>, and a <a href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#body-elements">number of other useful directives</a>.</p>
<h1 id="framework-framework-framework">Framework Framework Framework</h1>
<p>For a serious documentation project, you’re almost certainly using a framework for specific features and to extend the limit of the vanilla markup. In this section, let’s check out some of the popular frameworks for Markdown, Asciidoc, and reStructuredText.</p>
<h2 id="markdown-frameworks">Markdown frameworks</h2>
<p>Considering that the end result of a documentation project is often a static site, the words <strong>static site generator (SSG) tool</strong> and Markdown framework can be used interchangeably. Here are my top five picks:</p>
<ol>
<li>
<p><a href="https://github.com/jekyll/jekyll">Jekyll</a>, the engine behind GitHub Pages, was the most popular SSG until Hugo came out. Written in Ruby, Jekyll is a great choice for writing blog sites. Jekyll can take your content written in Markdown and Liquid templates and render them to a static website deployed to a server of your choice. The site you’re currently on is <a href="https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll">built using Jekyll and GitHub Pages</a>.</p>
</li>
<li>
<p><a href="https://gohugo.io/">Hugo</a> is probably the most popular open-source static site generator. Written in Go, Hugo builds sites at a blistering speed. It has a native support for a variety of content types, menus, and dynamic API-driven content. These don’t require you to use an additional plugin. You can select a theme that suits your project from <a href="https://gohugo.io/showcase/">a wide selection</a>. Check out <a href="https://gohugo.io/showcase">some of the project websites</a> that are built with Hugo.</p>
</li>
<li>
<p>Released in 2022, <a href="https://markdoc.dev/">Markdoc</a> is a relatively new Markdown-based authoring framework. The Markdoc project is <a href="https://github.com/markdoc/markdoc">open-source</a> and it powers <a href="https://stripe.com/docs">Stripe’s documentation</a>. Their website has a <a href="https://markdoc.dev/">live edit</a> button which makes the website a playground for you to give Markdoc a try. Documentations created with Markdoc will automatically render with your <a href="https://markdoc.dev/docs/examples/react">React</a> app and using <code class="language-plaintext highlighter-rouge">@markdoc/next.js</code> for your <a href="https://markdoc.dev/docs/nextjs">Next.js</a> app.</p>
</li>
<li>
<p>Configured with a single YAML file, <a href="https://www.mkdocs.org/">MKDocs</a> is the fourth Markdown framework on my list, which falls in the category of SSG. Although there are not as many as in Hugo, MKDocs offers a <a href="https://www.mkdocs.org/user-guide/choosing-your-theme/">few official themes</a> and a number of <a href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">third party themes</a>. As a Python-based framework, you can use <code class="language-plaintext highlighter-rouge">pip</code> to install <a href="https://www.mkdocs.org/dev-guide/plugins/">MKDocs plugins</a>. You can follow <a href="https://www.mkdocs.org/getting-started/">this getting started guide</a> for your first MKDocs project.</p>
</li>
<li>
<p>Last, but certainly not least, among my favorite frameworks is the family of frameworks based on <a href="https://mdxjs.com/">MDX</a>. Before that, let’s understand what is MDX and how does it vary from MD.</p>
</li>
</ol>
<p>According to <a href="https://mdxjs.com/docs/what-is-mdx/#jsx">mdxjs.com</a>:</p>
<blockquote>
<p><a href="https://reactjs.org/docs/introducing-jsx.html">JSX</a> is an extension to JavaScript that looks like HTML but makes it convenient to use components (reusable things). MDX allows you to use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content.</p>
</blockquote>
<p>With over 40K GitHub stars, <a href="https://docusaurus.io/">Docusaurus</a> is undeniably one of the most popular modern documentation frameworks based on MDX. Docusaurus orignates from Meta Open Source (f.k.a Facebook) and is packed with content-centric features (docs, blog, pages, versioning, i18n, a11y, SEO…). As a <strong>React + Node.js static site generator</strong>, you can either use MD to get started easily or use MDX to make your docs look interactive. <a href="https://docusaurus.io/showcase">This showcase</a> of documentation sites using Docusaurus is enough to convince me that the UX and DX of a documentation site is as important as the content itself.</p>
<p>From the creators of <a href="https://nextjs.org/">NextJS</a>, the next SSG based on MDX is <a href="https://nextra.site/">Nextra</a>. Nextra offers advanced syntax highlighting, ease of i18n creation, out-of-the-box full text search, and Markdown link and image converted to <a href="https://nextjs.org/docs/routing/introduction#linking-between-pages">Next.js Link</a> and <a href="https://nextjs.org/docs/basic-features/image-optimization#local-images">Next.js Image</a>. With Nextra, you can write a blog or docs using the themes available. <a href="https://nextra.site/showcase">Here</a> are the sites that are built using Nextra.</p>
<p>Besides these five frameworks, <a href="https://notaku.so/">Notaku</a> gets an honorable mention that uses <a href="https://notaku.so/">Notion</a> as CMS to create documentation site. With SEO and site performance optimization out-of-the-box, Notaku can be a great choice for teams those are already using Notion.</p>
<h2 id="asciidoc-frameworks">Asciidoc frameworks</h2>
<ol>
<li>
<p>An implementation of the docs-as-code approach, <a href="https://github.com/docToolchain/docToolchain">docToolchain</a> is a collection of scripts that makes it easy to create and maintain powerful technical documentation. It is a popular open-source project that uses <a href="https://jbake.org/">jBake</a> under the hood as the SSG. docToolchain can <a href="https://doctoolchain.org/docToolchain/v2.0.x/015_tasks/03_task_publishToConfluence.html">publish to Confluence</a>, <a href="https://doctoolchain.org/docToolchain/v2.0.x/015_tasks/03_task_generatePDF.html">generate PDF</a> using an Asciidoctor plugin, and <a href="https://doctoolchain.org/docToolchain/v2.0.x/015_tasks/03_tasks.html">more</a>.</p>
</li>
<li>
<p><a href="https://asciidoctor.org/">Asciidoctor</a> is a Ruby-based text processor for parsing AsciiDoc into a document model and converting it to HTML5, PDF, EPUB3, and other formats. Built-in converters for HTML5, DocBook5, and man pages are available in Asciidoctor. Asciidoctor has an out-of-the-box default stylesheet and built-in integrations for MathJax (display beautiful math in your browser), highlight.js, Rouge, and Pygments (syntax highlighting), as well as Font Awesome (for icons). Although Asciidoctor is written in Ruby, that does not mean you need to know Ruby to use it. Asciidoctor can be executed on a JVM using <a href="https://docs.asciidoctor.org/asciidoctorj/latest/">AsciidoctorJ</a> or in any JavaScript environment (including the browser) using <a href="https://docs.asciidoctor.org/asciidoctor.js/latest/">Asciidoctor.js</a>. You can choose any one of three Asciidoctor processors (Ruby, JavaScript, Java/JVM) and get the same experience. You can also use the <a href="https://docs.asciidoctor.org/maven-tools/latest/">Asciidoctor Maven Plugin</a> to convert your Asciidoc documentation using Asciidoctor from an Apache Maven build.</p>
</li>
<li>
<p>Unlike docToolchain or Asciidoctor, <a href="https://antora.org/">Antora</a> is a true framework for Asciidoc that can store, retrieve, and aggregate all Asciidoc content from multiple git repositories. Antora’s page referencing system isn’t coupled to filesystem paths or URLs. You are able to cross reference pages across a local machine, a staging environment, and a production environment. To generate a site with Antora, you need the <a href="https://www.npmjs.com/package/@antora/cli">Antora CLI</a> and <a href="https://gitlab.com/antora/antora">Antora site generator</a>.</p>
</li>
</ol>
<h2 id="restructuredtext-framework">reStructuredText Framework</h2>
<p>If you’ve noticed the usage of “framework” instead of “frameworks” in the above heading, you can guess that there’s only one framework for reStructuredText. <a href="https://www.sphinx-doc.org/en/master/index.html">Sphinx</a>, originally created for Python documentation, takes plain-text files in reStructuredText format and transforms it into HTML, PDF, and any output formats. A few well-known projects that use Sphinx for documentation are <a href="https://docs.djangoproject.com/">Django</a> and <a href="https://docs.readthedocs.io/en/latest/index.html">ReadTheDocs</a>.</p>
<p><a href="https://www.sphinx-doc.org/en/master/index.html">Sphinx</a> is incredibly powerful and can offer a table of contents, automatic links for functions, automatic code highlighting using <a href="https://pygments.org/">Pygments</a>, and other capabilities using <a href="https://www.sphinx-doc.org/en/master/usage/extensions/index.html#builtin-extensions">built-in</a> or <a href="https://www.sphinx-doc.org/en/master/usage/extensions/index.html#third-party-extensions">third-party</a> extensions. If you’d like to use (a flavor of) Markdown with Sphinx, you can do so using <a href="https://myst-parser.readthedocs.io/en/latest/">MyST-parser</a> - a Sphinx and Docutils extension to parse <a href="https://jupyterbook.org/en/stable/reference/cheatsheet.html">MyST</a>.</p>
<p>However, <a href="https://twitter.com/choldgraf/status/1212054861132521472?s=20&t=SiZ3Pr5NnPbID0kNLYcisg">many folks complained</a> about the difficulty in surfacing and debugging errors that happen in the Sphinx build process. The fact that Sphinx build is significantly slower than other SSG frameworks, the development and writing flow takes a hit in the process.</p>
<h1 id="choose-the-right-markup-and-framework">Choose the right markup and framework</h1>
<p>If you’re a developer, learning the syntax and styling of a markup language is relatively easy compared to learning a programming language. When you learn the syntax of a markup language and can render an HTML page locally, you reach the <code class="language-plaintext highlighter-rouge">hello world</code> nirvana of documentation. However, the difficulty doesn’t necessarily start when you write the first documentation file. As you try more advanced tasks for your developer documentation project, you lean more on the <del>framework</del> community behind the framework.</p>
<p>I <a href="https://twitter.com/DewanAhmed/status/1583465169006448640?s=20&t=kOdJ_vOoZiZ_TJK0vJDK9A">asked on Twitter</a> about the choice among Markdown, AsciiDoc, and reStructuredText and the first version of this blog summarized the findings. When I published this blog back in November 2022, it got quite a few attentions and was trending on the <a href="https://news.ycombinator.com/item?id=33468213">first page of HackerNews</a>. Besides the satisfaction from the blog’s success, I felt terrible for missing out on tools like Jekyll, docToolchain, and Docusaurus. Thanks to <a href="https://twitter.com/mooreds">Dan Moore</a>, <a href="https://twitter.com/RalfDMueller">Ralf D. Müller</a>, <a href="https://twitter.com/sebastienlorber">Sebastien Lorber</a>, and the HackerNews commenters, I’ve updated this blog to include the missing tools.</p>
<h2 id="scripting-language-preference">Scripting language preference</h2>
<p><img src="/assets/images/2023/why-reST.png" alt="Why reST" /></p>
<p>The first line says it all! Almost every single question of “Why reST?” is answered with “because we have a bunch of Python devs…”.</p>
<p>Next is Markdown. If your project uses some form of workflow and you’d like to run some scripts within your Markdown, your choice of scripting language might vary from JavaScript (Jekyll, Markdoc, or Docusaurus) to GoLang (Hugo) to Python (MKDocs).</p>
<p>Unlike reStructuredText or Markdown frameworks, Asciidoc’s Antora framework provides extensive feature set out-of-the-box so that you don’t need to add scripting languages like Python, Ruby, or JavaScript within your documentation. Full disclaimer that my take is based on Antora’s website. An advanced user of the framework might be able to confirm this claim.</p>
<h2 id="syntax">Syntax</h2>
<p>Let’s look at a few syntax comparisons to understand how simplicity helps Markdown win many projects.</p>
<p>Link in reStructuredText:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>This is `Dewan's blog <https://www.dewanahmed.com>`_.
</code></pre></div></div>
<p>Link in Asciidoc:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>https://www.dewanahmed.com[Dewan's blog]
</code></pre></div></div>
<p>Link in Markdown:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>[This is Dewan's blog](https://www.dewanahmed.com)
</code></pre></div></div>
<p>Let’s take a look at header complexity in reStructuredText:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>This is a header
~~~~~~~~~~~~~~~~
</code></pre></div></div>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>======================
This is also a header
======================
</code></pre></div></div>
<p>The list of valid header characters in reStructuredText:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
</code></pre></div></div>
<p>Compare the above insanity to Markdown and Asciidoc:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code># This is a header in Markdown
## This is a sub-header in Markdown
</code></pre></div></div>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>= This is the Document Header (Level 0) in Asciidoc
== This is the Section Title (Level 1) in Asciidoc
</code></pre></div></div>
<p>Setting aside the annoyance of having to hold down the “=”, “~”, or another underline-like character a bunch of times, the big problem with reST headers is that header characters in reST have no single mapping onto the header hierarchy.</p>
<p>Similar to reST, critics say that AsciiDoc is less familiar to engineers and technical writers. AsciiDoc is said to have a number of syntactic idiosyncrasies, such as the use of <a href="https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/#nested-unordered-list">multiple leading asterisks</a> in order to express nested bulleted lists or <a href="https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/#nesting">varying the length</a> of the delimiter line to nest delimited content blocks.</p>
<h2 id="extendability">Extendability</h2>
<p>Many tech companies love the rich ecosystem of <a href="https://github.com/remarkjs">Remark</a> to transform Markdown with plugins. Still, <strong>extendability</strong> is the subject where Markdown historically scored the lowest. Most folks mention that Markdown is not suitable for serious documentation projects. Some teams might be tempted to include custom HTML and CSS within Markdown and then get stuck in a messy situation during migration to another framework.</p>
<p>Let’s think for a moment here 🤔 …</p>
<p>How often do you migrate your docs? Migrating any mature documentation project that uses some sort of framework is never easy. If you choose the wrong framework or overload your project with custom HTML/CSS/JS without taking advantage of a framework’s built-in feature, Markdown is not to blame here.</p>
<p>If you’re migrating your documentation project from one markup to another, you’ll want to know about projects like <a href="https://pandoc.org/">Pandoc</a>. If your build process includes a process to convert markup, Pandoc can be <a href="https://github.com/pandoc/pandoc-action-example">run with GitHub Actions</a>. If you’re planning on <a href="https://codeahoy.com/q/q502/How-to-convert-asciidoc-to-Markdown">converting Asciidoc files to Markdown</a>, you’ll have to take a detour via the XML route. The proces will be: <code class="language-plaintext highlighter-rouge">Asciidoc ---> XML ---> Markdown</code>.</p>
<p><a href="https://myst-parser.readthedocs.io/en/latest/">MyST-parser</a>, which is both completely compatible with CommonMark and also supports all ReStructured Text directives, can be used to convert reST to Markdown.</p>
<h2 id="internationalization-i18n">Internationalization (i18n)</h2>
<p>Internationalization (i18n) pain for a documentation project is a process problem, not a feature gap. Documentation frameworks are not meant to translate your developer docs for you into the language of your choice. Some frameworks might offer i18n <strong>support</strong>, like the <a href="https://docusaurus.io/docs/i18n/crowdin">Crowdin support in Docusauraus v2</a>. With Jekyll, you have to pick a theme <a href="https://github.com/kurtsson/jekyll-multiple-languages-plugin">like this one</a>. I doubt if the reST or adoc frameworks would differ much from this process. Besides the framework support, you’ll need a localization vendor like <a href="https://lokalise.com/">lokalise</a> or a community driven platform like <a href="https://crowdin.com/">Crowdin</a> to actually <strong>do</strong> the translation. Sébastien goes into great detail in this <a href="https://github.com/facebook/docusaurus/issues/3317">Docusaurus RFC</a> when discussing i18n support in Docusaurus v2.</p>
<h2 id="other-factors-when-considering-a-markup">Other factors when considering a markup</h2>
<p>If you need to maintain different versions of your documentation based on product releases, you need to carefully plan in advance. Copying file snapshots after every release is a BAD IDEA. This does not scale, and pretty soon you’ll exhaust your resources. The ideal way is to use docs-as-code and use git to manage the versions of your documentation.</p>
<p>Do you have parts of the documentation behind a firewall that require authentication to access them? You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.</p>
<h2 id="authoring-experience-️-user-experience">Authoring Experience ⚖️ User Experience</h2>
<p>Let’s look at some documentation sites with great UX:</p>
<table>
<thead>
<tr>
<th>Jekyll</th>
<th>Docusaurus</th>
<th>Antora</th>
<th>Sphinx</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://sketch.com/">Sketch</a></td>
<td><a href="https://docsearch.algolia.com/">Algolia</a></td>
<td><a href="https://solr.apache.org/guide/solr/latest/">Apache Solr</a></td>
<td><a href="https://docs.kernel.org/">Linux Kernel</a></td>
</tr>
<tr>
<td><a href="https://developer.spotify.com/">Spotify</a></td>
<td><a href="https://hasura.io/docs/">Hasura</a></td>
<td><a href="https://cassandra.apache.org/_/development/documentation.html">Apache Cassandra</a></td>
<td><a href="https://www.envoyproxy.io/docs">Envoy Proxy</a></td>
</tr>
<tr>
<td><a href="https://dev.twitch.tv/">Twitch</a></td>
<td><a href="https://www.supabase.io/docs">Supabase</a></td>
<td><a href="https://docs.cloudbees.com/">Cloudbees</a></td>
<td><a href="https://docs.aiven.io/">Aiven</a></td>
</tr>
</tbody>
</table>
<p>Humble brag that the last one in the list (<a href="https://docs.aiven.io/">Aiven</a> 🦀) won <a href="https://devportalawards.org/nominees/2022/aiven-developer">2022 DevPortal Awards</a> in the category <strong>Best DevPortal Beyond REST Platforms</strong>. If I added a list of great docs websites but didn’t include the OG, it would be a crime. Check out one of THE BEST documentation out there - <a href="https://stripe.com/docs">Stripe Docs</a>, built using <a href="https://markdoc.dev/">Markdoc</a>.</p>
<p>What makes a great user experience for a documentation site? The factors affecting your users are:</p>
<ol>
<li>general look and feel of your website</li>
<li>proper use of interactive components (although this is completely optional)</li>
<li>ease of finding information (including the correctness of the information)</li>
<li>features like <strong>copy code to clipboard</strong>, syntax highlighting on code, etc.</li>
<li>how less annoying your site is with things like pop-ups, tracking, etc.</li>
</ol>
<p>I like that you care deeply about your users. How about the folks who work really hard to build these docs? If the emoji is loading properly, you’ll see that I put a scale icon between authoring experience and user experience on the section heading. Here are the factors affecting your authors:</p>
<ol>
<li>ease of creating their first PR (you are using docs-as-code approach, right? RIGHT?)</li>
<li>maturity of the content architecture (Can I easily guess which sub-folder my new file will go under?)</li>
<li>level of scripting knowledge required to contribute (do I need to be a react dev to contribute to the docs?!)</li>
<li>automation within the content review/publication process to catch linting, spelling and other errors (this is not related to the markup/framework)</li>
<li>frequency of large migration projects (ideally “zero”)</li>
</ol>
<p>Points 2, 4 and 5 don’t relate to the choice of the markup language or framework. Depending on points 1 and 3, your docs contribution will include almost anyone from your company or only the DevRel team and technical writers.</p>
<p>Writing documentation is different from writing code.</p>
<p>Writing documentation is different from writing code.</p>
<p>Yes, I needed to repeat that line. As a user, I love the visually appealing documentation sites built using an MDX-based framework. While MDX affords users more power and flexibility, it comes at the cost of complexity. Content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment. You can choose an MDX-based framework for other features and stay away from overscripting. But the temptation (to add more scripts) is harder to resist than one might think.</p>
<p>With the above discussion, can we find a middle ground that balances both the user experience and authoring experience? While all 10 factors affecting user and authoring experiences are critical, some of the ones I mentioned above don’t relate to your choice of markup and framework (for example, content architecture or if you add too many pop-ups). I’ll highlight five questions you can ask when selecting a markup and framework.</p>
<p>Question 1: Do you have a strong reason for NOT using Markdown?</p>
<p>Question 2: How much do you care about the appearance of your docs site? Do you need a beautiful and interactive one that you can maintain over time?</p>
<p>Question 3: What are the features that matter to your users and authors? Search? Internationalization? Versioning? Pick the framework that delivers (most of) these features.</p>
<p>Question 4: Do you have a special need, like building docs from multiple git repositories or requiring authentication on certain parts of the documentation?</p>
<p>Question 5: Is the framework open-source?</p>
<h1 id="wrap-up">Wrap up</h1>
<p>In this blog, I covered three popular markup languages, some very popular frameworks, and my opinion on the choice of markup language and framework based on a few key factors. If there’s one thing you want to take away from this blog, it will be to find the balance between the ease of getting started (authoring experience) and the ease of finding information (user experience). If you liked this blog or have any feedback, please <a href="https://twitter.com/DewanAhmed">reach out</a>.</p>
<hr />
<h1 id="appendix">Appendix</h1>
<p>Since this blog had its day of fame on HackerNews, it has generated a lot of insightful discussions. It would be a shame not to capture at least some of them.</p>
<h3 id="addison-wrote"><a href="https://github.com/addisonj">Addison</a> wrote:</h3>
<p>I have spent a lot of time looking in this space recently for helping to revamp documentation and I really really have fallen in love with Markdoc.
Markdoc just hits the sweet spot of being super easy to get started with but elegantly extensible that makes it scale. I think the OP here simplifies a bit though of what Markdoc is. While it is pretty simple to integrate into a next.js site for a SSG doc site, it is more of a library that can be integrated into almost any site or rendering framework.</p>
<p>In some ways, this is the biggest “challenge” of Markdoc right now. It isn’t focused on a polished out-of-the-box experience like Docusaurus or MKDocs, but is instead more of a DIY tool.</p>
<p>That said though, what is there is really great. With the ability to create custom tags easily and then the ability to analyze and transform an AST in a simple, but easy to understand way, I think markdoc is actually a great option for more than just building a doc site, but as a more general purpose tool for authoring any text-heavy content.</p>
<p>With Markdoc, I have built:</p>
<ul>
<li>a higher level utility for creating a “library” of content with consistent ids for stable and validated links</li>
<li>a validation library to ensure that doc structures follows best practices like having metadata tags in the frontmatter, properly nests headers and doesn’t skip H3s, etc</li>
<li>an integration for authoring and reusing doc content in <a href="https://formidable.com/open-source/spectacle/">spectacle</a> presentations</li>
<li>a clear direction of how to “scale” docs-as-code as we were struggling to do that with a simple, flat file of markdown files</li>
</ul>
<p>I have started to toy with the idea of a more general purpose CMS built around markdoc… but in general, a really great tool and kudos to stripe team for building it :)</p>
<h3 id="anonymous1-wrote"><a href="https://news.ycombinator.com/user?id=innocentoldguy">Anonymous1</a> wrote:</h3>
<p>I’ve done a lot of research and testing with Markdown, Asciidoc, and reStructuredText to see which would work best for my company’s documentation needs. We ended up going with Asciidoc and Antora for the following reasons.</p>
<p>Asciidoc:</p>
<ul>
<li>
<p>Almost as simple as Markdown.</p>
</li>
<li>
<p>Less convoluted than reStructuredText.</p>
</li>
<li>
<p>Excellent support for complex tables, captions, callouts, etc.</p>
</li>
<li>
<p>We prefer Asciidocs table structure to Markdown’s since it is easier to create and maintain.</p>
</li>
<li>
<p>Excellent documentation.</p>
</li>
</ul>
<p>Antora:</p>
<ul>
<li>
<p>Comes with a default template, which makes building prototypes easier.</p>
</li>
<li>
<p>Ability to pull from multiple git repositories.</p>
</li>
<li>
<p>Native Asciidoc support.</p>
</li>
<li>
<p>Fast compile times.</p>
</li>
<li>
<p>Good documentation.</p>
</li>
</ul>
<p>Based on our research, I even migrated my personal 11ty sites from Markdown to Asciidoc and have been quite happy with it.</p>
<h3 id="anonymous2-wrote"><a href="https://news.ycombinator.com/user?id=MilStdJunkie">Anonymous2</a> wrote:</h3>
<p>I tend to agree with the author’s sentiment re: Asciidoc, but that is a subjective impression, driven by my industry and the requirements it imposes. (note that the first version of the blog suggested Asciidoc/Antora as the ideal choice).</p>
<p>Here. Let me tell you a story.</p>
<p>Some years ago, Leadership in <COMPANY REDACTED=""> decided to stop paying for the S1000D[1] software. This would make the publications group effectively homeless. The objective of this tactic was to force a move to the PDM system's tech writing system, which had previously been rejected by more or less everyone.</COMPANY></p>
<p>I put out a plan[2] to keep the S1000D architecture (filenames, books, links, etc) but use lightweight markup and open standards from the programming industry, to do the actual writing. Which lightweight markup language? I needed the following:</p>
<ul>
<li>
<p>Transclusion, need to bring in files (data modules) from a centralized publication module</p>
</li>
<li>
<p>Partial Transclusion, need to be able to bring in part of another file, what would be called CIRs in S1000D</p>
</li>
<li>
<p>Conditional content, usable inline, so that a step or a figure could be toggled on and off depending on a condition set in the Publication Module. This emulates Applicability in S1000D.</p>
</li>
<li>
<p>Complex print output</p>
</li>
<li>
<p>Nice-to-haves: an AST that maps to a legacy format aka DocBook/DITA/S1000D/MIL-STD-38784/etc; publishing pipelines capable of weird crap like complex front matter, TOC, indices, header/footer/margin running content; a singular standard that had some life in it</p>
</li>
</ul>
<p>I took pretty much every lightweight markup variant out for a spin with a test migration and publish, on my own time, nights and weekends. I found that there was a Markdown variant that could almost do everything I wanted, but it had a dependency on a document processor. ReST functionality similarly depended on notebooks and Sphinx. LaTeX HTML pipelines were a bit janky and hard to set up on Windows. Neither really tied to a legacy XML format, which limited round-tripping with something as insane as S1000D. And the print options for both ReST and MD were not where I needed them, particularly for tables, but also for running content. Asciidoc came the closest to checking off all the boxes for me.</p>
<p>Anyway, it happened, it worked, I did it. But it hit business process problems. Stuff that would have hit any new instance of a pubs too. Like “we don’t actually know which plane parts can work with each other” or “SMEs will never ever ever do a review in a text editor . . or electronically . . or in anything but a dead tree” or “a few writers don’t know what the scroll wheel on the mouse does”[3] or . . eh, take your pick. I ate my own gun, though, and left. They’re still using it - and probably still cursing my name - to this day. But that had been one of my big goals[4]: S1000D architecture on lightweight markup.</p>
<p>So. Lightweight markup. I haven’t continued to shop around, and I probably should. For one, I’m of the growing opinion that inline conditional content is a mistake as a general design, and that the conditionals should probably live in the processing layer. That’s a big chunk of the requirement covered by Asciidoc’s <code class="language-plaintext highlighter-rouge">include</code> directive. For another, I won’t deny that the Markdown ecosystem is about 100x the Asciidoc ecosystem, due to the much greater dev count with the JS ecosystem vs the Ruby ecosystem. Some of the toys in Markdownland are worth the move all by themselves. And round tripping S1000D? You can’t even round trip S1000D with itself.</p>
<p>Then again, there’s so many damn MD variants. .</p>
<p>[1] XML vocabulary for documentation of mil/aero systems. Think DITA but a million times more complicated. And a new Issue every two years, without any commonality in the scope.</p>
<p>[2] This was a mistake, as I made lasting enemies of the PDM boosters, who counted some executives among them. I would have been better off keeping my mouth shut and letting the whole thing sink into the ocean.</p>
<p>[3] And had no interest in finding out, either. “You’re trying to turn us into programmers, with this git and text stuff!”. No, no I am not, and if you ever want to work outside this sector you’ll want to learn what git is.</p>
<p>[4] Should probably mention that annual per seat license costs for the big S100D solutions were pushing past 30k, with reviewer licenses lagging not far behind that. Not including the setup costs, or the consultants that will have to fly down for every tweak and button. I could not, for the life of me, figure out how anyone manages to pay for that in avionics, where the margins are razor thin. Turns out they don’t, they just deeply discount their products so the OEM can “show them how it’s done”. Effectively they’re paying their suppliers with dollars that can only be spent with the OEM.</p>Dewan AhmedWho writes the developer documentation for your product? During the early days of my tech career, I worked on a database replication product at IBM. My immediate team had developers and testers but not a single technical writer. I can speak for myself when I say that I never bothered to know who keeps writing the lengthy and complex documentation for every release. Since then, many companies in tech (including companies like IBM) have taken a modern approach to documentation. This “modernization” started when more and more developers started writing documentation (not all developers hate writing docs 🤭). Having git running in their DNA, these developers wanted to bring in collaboration, version control, scripting, and easier bug tracking within developer documentation.Why are we paying these folks - a tale of DevRel2022-12-06T20:00:00-04:002022-12-06T20:00:00-04:00https://www.dewanahmed.com/why-paying-devrel<blockquote>
<p>I don’t have a technical background, so I’m looking to apply for a project manager, product owner, or developer advocate type of role.</p>
</blockquote>
<p>I offer pro bono career coaching outside of work hours, so I interact with a lot of jobseekers on a regular basis. Over the last few months, I’ve been observing a troubling trend. Folks who are trying to transition into tech from a non-technical background have mentioned something like the above. I had a mixed reaction to hearing this. On one end, I was super happy that more people know about developer advocacy and are interested in a career in it. However, on a more troubling end, I thought to myself, “Are these folks seriously thinking of developer advocacy as an <strong>easy way in</strong>?” Folks who are new to this industry might not know much about developer advocacy. It’ll be scary, however, if the tech leadership also sees developer advocates as fluff. In this blog, I will share my thoughts and provide reasoning to make three claims:</p>
<ol>
<li>Developer advocacy is a technical role.</li>
<li>Developer advocacy is NOT an entry-level role.</li>
<li>Your developer advocates are worth every penny you invest in them.</li>
</ol>
<p>In the foreword of <a href="https://www.persea-consulting.com/book">Mary’s book</a>, Jono Bacon wrote:</p>
<blockquote>
<p>Developer Relations … is a remarkably nuanced, complex, and <strong>context-specific</strong> discipline.</p>
</blockquote>
<p>I know I’m making three absolute claims without the comfort of an “it depends” answer. That is because I’ll set the context and boundary for each of my claims. Grab your favorite beverage, relax, and read on. This one doesn’t come with a TL;DR.</p>
<h2 id="who-is-a-developer-advocate">Who is a developer advocate?</h2>
<p>Since some of my readers might not know about developer advocacy, this section introduces the terminology. Feel free to skip this section if you’re familiar with the role.</p>
<p>There are many right ways and only one wrong way to understand the different components of Developer Relations (DevRel). The only way to go wrong is to become obsessed with how different companies structure and view their DevRel teams. For example, <a href="https://devrelbook.substack.com/p/developer-advocacy-doesnt-equal-developer">Developer Relations - The Book</a> breaks down DevRel into four functional areas: developer marketing, developer experience, developer education, and developer success. On the other hand, developer experience is a superset of developer relations, according to <a href="https://leerob.io/blog/dx">Lee Robinson at Vercel</a> or <a href="https://milendyankov.com/blog/2022/02/from_devrel_to_developer_experience/">Milen Dyankov at AxonIQ</a>. Developer relations can report to the engineering organization, such as Google, the product or marketing organization, such as AWS, or remain separate, such as Microsoft. All this to say that the definition and structure of developer relations can vary a lot.</p>
<p>However, in my opinion, the role and work of a developer advocate can be universally defined regardless of the company or the position in an org chart. <strong>A developer advocate is an experienced engineer who acts as a trusted voice between the company and the community/customer. They write clean code, produce reusable and developer-friendly content, and possess a tremendous level of empathy for the community</strong>. They can work as part of a developer relations team or as the solo developer advocate for their company. There are three important pieces in my definition of a developer advocate:</p>
<ul>
<li>Engineer (builder)</li>
<li>Trusted voice and experience</li>
<li>(Interface) between the company and the community/customer</li>
</ul>
<p>In the following three sections, I will discuss the reasoning behind my definition.</p>
<h2 id="developer-advocates-must-be-technical">Developer advocates MUST be technical</h2>
<p>In Canada, the term “engineer” is protected and reserved only for those licensed by a provincial or territorial engineering regulator. Let’s use the term “builder” instead. A builder is someone who has experience building software systems.</p>
<p>Developer advocates are storytellers. Oftentimes, these stories are about their own experiences solving critical technical challenges. Even when they’re building a demo application, their previous experience as builders helps them architect the application to follow the best practices. Most talks follow a question/answer period where the audience asks the developer advocate questions about the technology they talked about. Even if someone (without the technical foundation) manages to rehearse and deliver a technical talk, answering the audience’s deep technical questions will be extremely difficult. </p>
<p>If you think that not all developer advocates need to be technical and that some folks might be more on the community side, you might be mixing community managers with developer advocates. Community managers are also part of a developer relations team, and their work overlaps some of the work of developer advocates in the community. If you see a developer advocate doing only community work and no code or technical content, they may be using the incorrect title for whatever reason. On LinkedIn, I saw a sales representative with the title “Sales Rep / Developer Advocate.”</p>
<p>What do I mean by “code or technical contents”? In the current time and market, almost everyone at a tech company can talk technical. Even basic knowledge of git and GitHub are considered general skills. You must return to your audience—the developers—to find the bar of code and technical content. Developers have an uncanny ability to smell sales and marketing tactics. However, they constantly seek technical knowledge from blogs and (reluctantly) skim through developer documentation. Your developer audience is the litmus test for the code and contents your developer advocate creates. Your developer advocate should somehow make developers’ lives easier through advocacy and content creation.</p>
<p>Why am I trying to be a gatekeeper, though? I don’t think anyone can/should be a gatekeeper in tech, but my opinions in this blog are coming from a genuine concern that some folks might be devaluing the developer advocacy role. When I was interviewing for my first job change after 8 years in 2020, I was fortunate to receive a flood of emails for DevRel roles. Unfortunately, a good percentage of these roles were for blockchain/crypto/NFT companies. What’s unfortunate about it?</p>
<p>I respect all technologies and legal companies. Here is the <strong>unfortunate</strong> bit ➡️ Almost every single recruiter from these companies assured me that I didn’t need to know ANYTHING about blockchain or the underlying technology to join their companies. This is after I mentioned that I don’t have a clue about blockchain. What was important for these companies then? A large social media following and the ability to create endless marketing contents. I don’t follow that industry, but I can make a guess that without the technical foundation, most of the blockchain/crypto/NFT DevRel hires were unsuccessful at building the <strong>trust</strong> of their communities.</p>
<p>Do you have a favorite developer advocate? I follow and respect a number of developer advocates in the industry. Let’s take a look at their background and try to deduce if a technical background is needed or not to become a successful developer advocate.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Roles before DevRel</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://en.wikipedia.org/wiki/Kelsey_Hightower">Kelsey Hightower</a></td>
<td>Software Engineer, IT Consultant, SysAdmin</td>
</tr>
<tr>
<td><a href="https://twitter.com/techgirl1908">Angie Jones</a></td>
<td>Java Champion, Software Engineer, Inventor {26 patents}</td>
</tr>
<tr>
<td><a href="https://www.linkedin.com/in/mattstratton/">Matty Stratton</a></td>
<td>Lead Engineer, Infrastructure Architect, Technical Consultant</td>
</tr>
<tr>
<td><a href="https://lornajane.net/">Lorna Jane</a></td>
<td>PHP Consultant, Principal Developer, Senior Web Developer</td>
</tr>
<tr>
<td><a href="https://www.linkedin.com/in/saivennam/">Sai Vennam</a></td>
<td>Software Engineer, Web Developer</td>
</tr>
</tbody>
</table>
<p>I hope I was able to explain why developer advocacy is and will remain a highly technical role.</p>
<h2 id="developer-advocacy---not-an-entry-level-role">Developer advocacy - NOT an entry-level role</h2>
<p>Before I transitioned into tech, I worked as an electrical engineer building renewable energy systems. I also spent 10 years at engineering schools in two countries, where my brain was hammered to learn new things by reading documentation (a.k.a. books), and then I built systems (a.k.a. lighting up an LED) using that knowledge. Even with all that technical experience, it would be impossible for me to start my tech career as a developer advocate. I knew a lot about circuits, diodes, and huge transformers but nothing about SQL or git, let alone cloud and Kubernetes. I started as an intern at IBM, worked my way up as a Java developer, and then transitioned to technical consulting. After 4 years of experience as a developer and consultant, I was able to start my developer advocacy career.</p>
<p>Your path can be very different. You can be a CS grad or a college dropout, a physics PhD or a musician - but you need the experience of building software systems before trying to teach others how to do so. Whether it’s for two years or twenty, legacy enterprise development or freelance open-source contributions, a developer advocate must have <strong>done the thing</strong> that they are hoping to teach others. Without the technical experience, how can you teach a bunch of techies? <a href="https://github.com/readme/guides/angie-jones-demystifying-developer-advocacy">Angie Jones writes</a>:</p>
<blockquote>
<p>Developer advocates have to build and maintain credibility with their engineering peers, understand their pain points, and foresee how given solutions would address their needs. Without engineering experience, this is hard to do. Not impossible, but definitely hard.</p>
</blockquote>
<p>Does DevRel look glamorous from the outside? The travel, staying at nice hotels, and “influence” on social media might send all the wrong signals to someone looking to break into tech. Maybe we should talk more about the invisible hard stuff on the job. When I’m in my hotel room, I’m practicing in front of a mirror for my talk the next morning and not sipping on a pina colada by the pool. I’ve spent countless nights at airports and on economy flights without much sleep. I’ve had layovers at airports without a proper restaurant and survived on granola bars and Coke Zero. On economy flights, wearing N95 masks can be anything but glamorous.</p>
<p align="center">
<img src="/assets//images/2022/program-age-vs-employee-experience-devrel.jpeg" alt="Program Age vs. Employee Years of DevRel Experience. Image credit: [Taylor Barnett](https://twitter.com/taylor_atx) and [2022 State of Developer Relations report](https://www.stateofdeveloperrelations.com/)" width="600" />
</p>
<p>Image credit: <a href="https://twitter.com/taylor_atx">Taylor Barnett</a> edited the above image from <a href="https://www.stateofdeveloperrelations.com/">2022 State of Developer Relations report</a> and <a href="(https://twitter.com/taylor_atx/status/1575218433632804864?s=20&t=WwyR42KTOQPJ4zWn4mqmrw)">tweeted</a></p>
<p><a href="https://twitter.com/taylor_atx">Taylor Barnett</a> wrote on Twitter about her hypothesis on why companies with new DevRel programs are hiring inexperienced folks. She mentioned that this is dangerous to the person they are hiring (more likely to leave the field), dangerous to the industry, and just dangerous to the company’s success. On her blog, <a href="https://taylorbar.net/posts/adventures-in-solo-devrel-notes/">Taylor wrote</a> about the challenges of DevRel. Although aimed at solo DevRels, developer advocates in general, are likely to burn out due to unclear prioritization and a lack of support/understanding from the larger teams (marketing, engineering, product, etc.). This likelihood of burnout increases by a few magnitudes if this DevRel person is an intern or have very little experience.</p>
<p>There can be a handful of exceptions, like Twilio back in the day or GitHub in the present, where they had/have programs to hire, support, and grow junior DevRel talents. But this is an exception, not an excuse, for companies to hire cheap DevRel talent and then set them up for failure. How is this dangerous for the company and the industry? This question creates a nice segue to my final claim. More on that in the next section.</p>
<h2 id="cost-of-devrel-depends-on-how-you-value-them">Cost of DevRel depends on how you value them</h2>
<p align="center">
<img src="/assets//images/2022/devrel-layoffs.jpg" alt="DevRel mass layoffs in 2022" width="600" />
</p>
<p>2022 was a troubling year for tech. However, with all the mass layoffs, don’t associate the troubling trend of DevRel layoffs only with mass layoffs. DevRel layoffs happened this year, the year before, and the year before. In my observations, there are three main reasons behind DevRel layoffs:</p>
<ol>
<li>Company-wide mass layoffs</li>
<li>The company never needed DevRel</li>
<li>The leadership didn’t understand DevRel</li>
</ol>
<p>When the company needs to tighten the belt, only the folks directly contributing to the revenue make the cut, and their colleagues find a place on the chopping board. I will be out of my mind to say that a company should let go of a developer over a developer advocate. Mass layoffs are unsightly and brutal, and they frequently result from Silicon Valley’s rush to become the next unicorn. But that is sometimes the unfortunate reality and cannot be avoided.</p>
<blockquote>
<p>DevRel - for every developer, not for every company</p>
</blockquote>
<p>Why do you think you need a developer relations team? Did you get Series A funding, and one of the investors suggested you get one of those developer advocate things? The question to ask is pretty simple. <strong>Does your company have a product or (open-source) project whose users are developers?</strong> For example, Gmail is used by the general population, but Google Cloud is used by developers.</p>
<p>Once you’re convinced that you need a developer advocate, or a DevRel team, it’s paramount to hire the first DevRel at the right time. Adam FitzGerald, Vice President of Developer Relations at HashiCorp, <a href="https://www.ggvc.com/insights/five-tips-for-building-a-successful-developer-relations-program-from-hashicorp/">mentioned to GGV</a> that the right time to formally create a developer relations program is when your company has about 25-50 people. Adam added that by the time your company has 100 employees, you almost certainly should have a head of developer relations, if you don’t already. While this is not exact science, this formula has worked well for many companies, including HashiCorp, which is considered the poster child for building successful open-source and developer relations programs.</p>
<p>In the majority of failed DevRel cases, the company leadership failed to understand the value of DevRel. When the pandemic hit in early 2020, I was working as a developer advocate at IBM. With all of the in-person conferences and meetups being cancelled, IBM leadership might have thought, “No events == No need for DevRel”. Many of our DevRel peers were let go, and the remaining were forced to move into some sort of client engineering roles. At the time of writing this blog, <a href="https://twitter.com/gracejansen27">Grace Jansen</a> and <a href="https://twitter.com/jjasghar">JJ Asghar</a> might be the last two DevRel standing at IBM. That, too, is probably because of how insanely awesome they are at their advocacy work. I can write a book on my lessons from the IBM DevRel days, but let’s set that aside for now.</p>
<p>Majority of companies layer DevRel on top of marketing as a sort of afterthought, and that’s usually a recipe for failure. All four co-founders at <a href="https://aiven.io/">Aiven</a> (the company where I work at) have been long-time open-source maintainers/contributors and highly value the work of DevRel. Similar examples can be seen at HashiCorp, where co-founder Armon Dadgar has been doing DevRel on the whiteboard since the early days of the company. Technical founders know the value of DevRel and know when to form a DevRel team. This is very different from bringing your first DevRel hire onboard and making them convince the leadership why the company needs DevRel in the first place. If your developer advocate needs to explain to the technical leadership the need for DevRel, that’s a red flag for that individual and the company.</p>
<hr />
<p>If you’re trying to transition into DevRel without technical experience, kudos to you for making this decision. But please don’t think of DevRel as a shortcut into a career in tech. Gain some experience building software systems, try to walk in the shoes of developers, and understand the pain points. There will be a time when you feel confident enough to make the move. Till then, work on your public speaking and writing skills.</p>
<p>If you’re hiring for DevRel talent, you’re paying a premium salary equivalent to the same level on the engineering ladder. You are completely justified in questioning this cost. What value is DevRel bringing? DevRel is the <strong>only</strong> team at your company that can speak the engineer’s language, provide regular feedback to the product team, function as a marketing team, and grow the community as the face of your company. Read the last line again and again until you realize why DevRel and developer advocates are worth every penny you invest in them.</p>Dewan AhmedI don’t have a technical background, so I’m looking to apply for a project manager, product owner, or developer advocate type of role.ripgrep - an extremely fast grep alternative2022-08-29T02:00:00-03:002022-08-29T02:00:00-03:00https://www.dewanahmed.com/ripgrep<p>If you’ve used <a href="https://man7.org/linux/man-pages/man1/grep.1.html">grep</a> to search for text or patterns in files, you’ll love <a href="https://github.com/BurntSushi/ripgrep">ripgrep</a> - a command-line utility tool written in <a href="https://www.rust-lang.org/">Rust</a>. By default, <code class="language-plaintext highlighter-rouge">ripgrep</code> will respect gitignore rules and automatically skip hidden files/directories and binary files. <code class="language-plaintext highlighter-rouge">ripgrep</code> is grep on steroids. It’s super fast for searching patterns within single files and huge directories of files. In this blog, I’ll help you get started with using <code class="language-plaintext highlighter-rouge">ripgrep</code> and hope it’ll help you become more productive on the command-line.</p>
<h2 id="installation-and-sample-data">Installation and sample data</h2>
<p>The first thing you’ll do is install <code class="language-plaintext highlighter-rouge">ripgrep</code>. It has first class support on Windows, macOS and Linux. Choose one of many <a href="https://github.com/BurntSushi/ripgrep#installation">installation options</a> or you can <a href="https://github.com/BurntSushi/ripgrep#building">build it from source</a>. Fortunately, the binary is not called <code class="language-plaintext highlighter-rouge">ripgrep</code>; it’s <code class="language-plaintext highlighter-rouge">rg</code>.</p>
<p>I have generated some sample server data which I’ll use to test drive <code class="language-plaintext highlighter-rouge">ripgrep</code>. Feel free to download <a href="https://gist.github.com/dewandemo/26797dfbc2d3839bfe29621015566e8e">this public gist</a> to play along. Each <code class="language-plaintext highlighter-rouge">mock-server-dataX.json</code> file has 1000 random server data and <code class="language-plaintext highlighter-rouge">mock-server.conf</code> file has a sample PostgreSQL configuration data.</p>
<h2 id="searching-within-a-single-file">Searching within a single file</h2>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rg port mock-server-data1.json
</code></pre></div></div>
<p>We’re telling <code class="language-plaintext highlighter-rouge">ripgrep</code> to search for the pattern “port” within a single file. You should see a 1000-line output since every object in that JSON array contains the “port” field.</p>
<p>Let’s try something specific:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rg 9778b33b-2c49-4340-a9b5-320339052ec0 mock-server-data1.json
</code></pre></div></div>
<p>When searching for a particular UUID within the file <code class="language-plaintext highlighter-rouge">mock-server-data1.json</code>, you should see only one row as a result. This is helpful. But does this UUID exist in other files?</p>
<h2 id="recursive-search">Recursive search</h2>
<p>Since <code class="language-plaintext highlighter-rouge">ripgrep</code> searches recursively by default, you don’t have to do anything special other than omitting the individual file name.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rg 9778b33b-2c49-4340-a9b5-320339052ec0
</code></pre></div></div>
<p>Since you didn’t specify a file name, <code class="language-plaintext highlighter-rouge">ripgrep</code> will search the current directory and sub-directories for files that contain the UUID <code class="language-plaintext highlighter-rouge">9778b33b-2c49-4340-a9b5-320339052ec0</code>.</p>
<p><img src="/assets/images/2022/ripgrep-recursive.png" alt="Recursive search" /></p>
<p>Not only <code class="language-plaintext highlighter-rouge">ripgrep</code> color-codes the search result, it also tells us the line number on the files where the pattern appears. Let’s validate this finding:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>vim +203 mock-server-data3.json
</code></pre></div></div>
<p>The above command opens <code class="language-plaintext highlighter-rouge">mock-server-data3.json</code> on line 203. Did you know this vim shortcut? <code class="language-plaintext highlighter-rouge">:set nu</code> will confirm that the UUID <code class="language-plaintext highlighter-rouge">9778b33b-2c49-4340-a9b5-320339052ec0</code> is shown on this line.</p>
<h2 id="pattern-search">Pattern search</h2>
<p>The test data has some errors. Some of the fields contain emails although there isn’t a field for email. Let’s use regex to find these anomalies:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rg -e "[a-zA-Z0-9_]+@[a-z]+.[a-z]+" .
</code></pre></div></div>
<p>The <code class="language-plaintext highlighter-rouge">-e</code> flag is the regex option and the above is a poorly built email regex. The output is as follows:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>./mock-server-data2.json
104: "password": "test@test.com"
./mock-server-data3.json
152: "password": "test@test.com"
288: "password": "info@info.ca"
./mock-server-data1.json
48: "password":"test@test.com"
112: "password":"test@test.com"
</code></pre></div></div>
<p>We can see that some of the password fields incorrectly contain emails. Theoretically, it’s possible that someone might be using the email as the password. But considering that these are randomly generated server passwords, we’ll treat these as errors.</p>
<h2 id="gitignore-and-hidden-files">gitignore and hidden files</h2>
<p><code class="language-plaintext highlighter-rouge">ripgrep</code> won’t show these file types <code class="language-plaintext highlighter-rouge">.rgignore</code>, <code class="language-plaintext highlighter-rouge">.gitignore</code>, and <code class="language-plaintext highlighter-rouge">.ignore</code>
in search results. Although you can disable all ignore-related fltering with the <code class="language-plaintext highlighter-rouge">--no-ignore</code> flag. <code class="language-plaintext highlighter-rouge">ripgrep</code> will also respect repository specific rules found in <code class="language-plaintext highlighter-rouge">$GIT_DIR/info/exclude</code>, as well as any global ignore rules in your <code class="language-plaintext highlighter-rouge">core.excludesFile</code>.</p>
<p>Let’s test this out:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rg tcp_keepalives_count
</code></pre></div></div>
<p>The output:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>mock-server.conf
84:#tcp_keepalives_count = 0 # TCP_KEEPCNT;
</code></pre></div></div>
<p>Let’s add <code class="language-plaintext highlighter-rouge">mock-server.conf</code> file to <code class="language-plaintext highlighter-rouge">.gitignore</code>, <code class="language-plaintext highlighter-rouge">.ignore</code>, or <code class="language-plaintext highlighter-rouge">.rignore</code>.</p>
<p>Now if you re-run the previous search, there wouldn’t be any output since <code class="language-plaintext highlighter-rouge">ripgrep</code> is filtering the <code class="language-plaintext highlighter-rouge">mock-server.conf</code> file out of the search.</p>
<h2 id="performance">Performance</h2>
<p>To get the maximum performance, <code class="language-plaintext highlighter-rouge">ripgrep</code> runs in a multi-threaded way which means that the result shown will not be in the same order for the same search running multiple times. The way <code class="language-plaintext highlighter-rouge">ripgrep</code> sorts the output is based on whichever file gets searched first. You can pass the <code class="language-plaintext highlighter-rouge">--sort</code> flag to sort the output which will come at the cost of some performance.</p>
<p>The line number and color cording are not the main selling point (it’s open-source so no one’s selling you anything :wink:) for <code class="language-plaintext highlighter-rouge">ripgrep</code>. Its main feature is being extremely fast and the author <a href="https://blog.burntsushi.net/">Andrew Gallant</a> wrote a <a href="https://blog.burntsushi.net/ripgrep/">detailed blog</a> on <code class="language-plaintext highlighter-rouge">ripgrep</code> benchmark.</p>
<hr />
<p>I was inspired by Brodie Robertson and Jay LaCroix to use <code class="language-plaintext highlighter-rouge">ripgrep</code> so thank you both. If you’ve given <code class="language-plaintext highlighter-rouge">ripgrep</code> a try, please <a href="https://twitter.com/DewanAhmed">let me know</a> how your experience was.</p>Dewan AhmedIf you’ve used grep to search for text or patterns in files, you’ll love ripgrep - a command-line utility tool written in Rust. By default, ripgrep will respect gitignore rules and automatically skip hidden files/directories and binary files. ripgrep is grep on steroids. It’s super fast for searching patterns within single files and huge directories of files. In this blog, I’ll help you get started with using ripgrep and hope it’ll help you become more productive on the command-line.Let’s NOT have a beer2022-08-18T21:00:00-03:002022-08-18T21:00:00-03:00https://www.dewanahmed.com/alcohol-obsession-in-tech<p>For the first time, I won a major raffle at a recent conference. However, I had to give the prize back since it was a beer dispenser and I don’t drink. If your reaction after reading the last line was “Why don’t you drink?” or “Most of us do and it’s your choice that you missed out.”, then this blog is for you. I’m calling out the alcohol obsession we have in the tech industry and how it’s causing a serious problem for many.</p>
<p>Let’s start with a beer dispenser as a prize. To be fair to the organizers (who hosted an awesome conference), all but this gift were regular ones, and by pure coincidence, the only alcohol-related prize was won by the person who doesn’t drink. However, selecting a beer dispenser as a prize implies that “everyone drinks” or “drinking is the <strong>default</strong> and opting out is <strong>optional</strong>. That’s a pattern I’ve seen at conferences, meetups, and even during hiring.</p>
<p>You might ask, “What’s the problem if folks drink? Others don’t have to, and they can choose a non-alcoholic drink.” Let me recall my last networking event from a conference (yup, the same one where I won a beer dispenser, but the experience is the same for any networking socials). People were handed out a beer ticket, and the servers were going around taking drink orders. By the time I stopped a server to ask if there were any non-alcoholic drinks, all the folks in my circle had a glass in their hands. The server (who was a little amused by my request) had to think about what they had that wasn’t alcohol but was gracious enough to bring me a pineapple juice. </p>
<p>Opting for a non-alcoholic beverage is a minor issue. While it was a networking event for a tech event, almost all the discussions revolved around different types of alcohol - taste, brewing techniques, etc. Needless to say, I had zero opinion on this topic and it barred me from engaging in most discussions. I made some failed attempts to steer the conversation back to something generic like tech, the area, food, etc. But somehow, the topic of alcohol seems to overpower all other topics in networking socials.</p>
<p>The work culture in general is alcohol-focused, especially in consulting and sales organizations. Closed a deal? Let’s open up a champagne bottle! Friday night? Let’s have a beer after work! Most folks don’t understand the effect of peer pressure on those who don’t drink or are in an early stage of recovery from alcohol problems. Having an event in a bar or a pub is problematic in and of itself. The counterargument is that “Most folks have a good time with a drink”. If one needs alcohol to have a good time, then there’s a bigger problem to deal with. Small cities might not have a variety of restaurants or meeting places, and a bar or pub might be the only option. Even then, you can make arrangements to have a wider option of non-alcoholic beverages and make an active effort so that the discussions don’t center around alcohol.</p>
<p>I remember an ex-colleague who used to say, “I want to hire someone with whom I can have a beer after work”. I totally understand that the underlying meaning was to hire like-minded folks and not dismiss folks who don’t drink. With remote work, this is much less of a problem. But if you’re in sales or consulting, you know that many important decisions are made over beers. If you don’t drink, you’re an outcast, and you’ll miss out on a lot of opportunities. This is not limited to sales or consulting departments. You might say that your team or organization doesn’t have this culture. Please know that you’re an exception. Kudos to your team, but your individual experience doesn’t reflect the majority. From hiring to promoting employees, culture fit plays a key role, and alcohol is a silent but significant contributor to culture fit.</p>
<p>Drinking alcohol is legal in many parts of the world. Canada legalized cannabis in October, 2018. Imagine going to a meetup or work event where everyone is smoking weed and they’re discussing how to grow good quality cannabis. If you are not a cannabis user, you will feel out of place at that event. Many of us feel the same at work events where alcohol is served and celebrated. You’re well within your rights to enjoy alcohol. Please, however, make certain that your enjoyment does not come at the expense of inclusivity and the safety of others.</p>Dewan AhmedFor the first time, I won a major raffle at a recent conference. However, I had to give the prize back since it was a beer dispenser and I don’t drink. If your reaction after reading the last line was “Why don’t you drink?” or “Most of us do and it’s your choice that you missed out.”, then this blog is for you. I’m calling out the alcohol obsession we have in the tech industry and how it’s causing a serious problem for many.StackConf 2022 Conference - Reflection2022-08-12T01:50:00-03:002022-08-12T01:50:00-03:00https://www.dewanahmed.com/stackconf<p>Last month I travelled across the pond to attend and give a talk at <a href="https://www.youtube.com/watch?v=I_xBBGeFULU">StackConf EU 2022</a> - an open-source infrastructure-focused conference. After two virtual events in 2020 and 2021, the conference took place live this year in the capital city of Berlin. The two-day conference was packed with exciting talks from industry leaders in the areas of cloud, DevOps, databases, machine learning, and other areas. You can check out the <a href="https://stackconf.eu/archives/2022-2/">conference archive</a> for recordings of all the talks. In this blog, I write about my favorite talks and moments from StackConf.</p>
<p><img src="/assets/images/2022/stackconf-speakers-dinner.jpg" alt="Speakers' dinner" /></p>
<p align="center">
Speakers' dinner on the evening before the conference
</p>
<h2 id="july-19---talks-to-talk-about">July 19 - Talks to talk about</h2>
<p>The first talk I’m excited to mention is “Scaling the Grail – Cloud-Native Computing on Encrypted Data using Carbyne Stack”. I met <a href="https://twitter.com/SvenTrieflinger">Sven Trieflinger</a> on the evening before the conference during the speakers’ dinner. Sven mentioned that Carbyne Stack relies on Secure Multiparty Computation (MPC) to keep data encrypted end-to-end: in transit, at rest, and in use. Although started at Bosch, the <a href="https://github.com/carbynestack/carbynestack">Carbyne Stack</a> project is now open-source and is gaining traction to build scalable infrastructure for sensitive data workloads.</p>
<p>Whether it’s a one repo for all or having no test for infrastructure, <a href="https://twitter.com/KrisBuytaert">Kris Buytaert</a> talked about the different patterns and anti-patterns
we’ve seen over the past decade of automation. It was reassuring to see that some of the points I was going to mention in my talk are repeated in other speakers’ talks as well - for example, the challenges around configuration drift for infrastructure as code.</p>
<p><img src="/assets/images/2022/stackconf-kris-talk.jpg" alt="Kris Buytaert talk" /></p>
<p align="center">
Kris Buytaert talk
</p>
<p><a href="https://twitter.com/PeterZaitsev">Peter Zaitsev</a>, the founder and CEO of Percona, gave a high-level talk on databases and storage in the cloud. Here are the types of storage to consider, according to Peter:</p>
<ul>
<li>Node local storage</li>
<li>Network attached block storage</li>
<li>Network file system</li>
<li>HTTP(S) accessible object store</li>
<li>Queues/Streams/Pipelines</li>
<li>Databases</li>
</ul>
<p><img src="/assets/images/2022/stackconf-peter-talk.jpg" alt="Peter Zaitsev talk" /></p>
<p align="center">
Peter Zaitsev talk
</p>
<p>Peter mentioned “shapechangers”, i.e., some databases that can speak multiple protocols. For example, ClickHouse can speak PostgreSQL and MySQL protocols, while FerretDB allows you to use PostgreSQL as if it were MongoDB, etc. It was nice to see a mention of Aiven in Peter’s slides.</p>
<p><a href="https://twitter.com/geekygirldawn">Dr. Dawn Foster</a> from VMware talked about the dynamics of collaboration among individuals, companies, and communities in her talk “How to Be a Good Corporate Citizen in Open Source”. She emphasised that community comes <strong>before</strong> company or individual needs. It’s better for the company to align their goals with the community/project goals rather than try to push something that the community/project does not benefit from. Most folks in the room were quick to snap a photo of the reference slide that Dawn shared, which included the following useful links:</p>
<ul>
<li><a href="https://todogroup.org/">The Linux Foundation TODO Group</a></li>
<li><a href="https://github.com/cncf/project-template">TAG Docs & Templates for CNCF Contributor Strategy</a></li>
<li><a href="https://github.com/theopensourceway/guidebook">The Open Source Way Guidebook</a></li>
</ul>
<h2 id="july-20---talks-to-talk-about">July 20 - Talks to talk about</h2>
<p>The next morning, I kicked-off StackConf with my own talk, “Do NOT click-ops your data infrastructure”. I hope it’s okay for me to shamelessly plug my talk. In my talk, I made a point about using automation tools like Terraform to build and manage data infrastructure rather than manually creating the resources. During the demonstration, I used <a href="https://developer.aiven.io/docs/products/kafka.html">Aiven for Apache Kafka®</a> and <a href="https://developer.aiven.io/docs/products/kafka/kafka-mirrormaker.html">Aiven for Apache Kafka® MirrorMaker 2</a> to demonstrate cross-cluster replication and how <a href="https://developer.aiven.io/docs/tools/terraform.html">Aiven Terraform Provider</a> can be used to deploy all resources in your preferred cloud. You can check out the recording of my talk <a href="https://www.youtube.com/watch?v=YBxt5uLz00I">on YouTube</a>.</p>
<p><img src="/assets/images/2022/stackconf-dewan-talk.jpg" alt="Dewan Ahmed talk" /></p>
<p align="center">
Dewan Ahmed talk
</p>
<p>I got into a real dilemma when two of the talks I wanted to attend were happening at the same time. <a href="https://twitter.com/horovits">Dotan Horovits</a> from Logz.io, a seasoned developer advocate, had a great talk “Open Source for Better Observability” and <a href="https://twitter.com/sayabanik">Sayantika Banik</a> from Quansight was covering data pipelines using open-source.</p>
<p><img src="/assets/images/2022/stackconf-dotan-talk.jpg" alt="Dotan Horovits talk" /></p>
<p align="center">
Dotan Horovits talk
</p>
<p>I really liked how Dotan broke down the open-source observability into “what”, “why”, and “where”:</p>
<ul>
<li>Metrics (the “what”): Prometheus, OpenMetrics, Grafana</li>
<li>Logs (the “why”): OpenSearch</li>
<li>Traces (the “where”): Jaeger, Zipkin, Apache SkyWalking®</li>
</ul>
<p>Sayantika had “fun” in her talk title, so that drew a lot of folks to her talk. She used <a href="https://github.com/dagster-io/dagster">Dagster</a> - an open-source orchestration tool for the development, production, and observation of data assets. If you’d like to learn about the basics of data pipeline by doing so, check out <a href="https://github.com/sayantikabanik/DataJourney">her GitHub repo</a>.</p>
<p><img src="/assets/images/2022/stackconf-sayantika-talk.jpg" alt="Sayantika Banik talk" /></p>
<p align="center">
Sayantika Banik talk
</p>
<p>My friend and ex-colleague <a href="https://twitter.com/jjasghar">JJ Asghar</a> from IBM gave a super interesting talk titled “We accidentally created a Serverless Application”. I took a ride from JJ on my way from the airport, so I was indebted enough to attend his talk ;). While waiting for the talk to start, JJ amused the audience with an unlimited supply of dad-jokes as GIFs. JJ mentioned the challenges where he and the team supported Kubernetes cluster creation requests and the entire process was manual. JJ’s talk was a step-by-step recollection of how he made the process automated, and that was the serverless application he developed “accidentally”.</p>
<p><img src="/assets/images/2022/stackconf-jj-talk.jpg" alt="JJ Asghar talk" /></p>
<p align="center">
JJ Asghar talk
</p>
<p><a href="https://twitter.com/laura_hamham">Laura Ham</a> from SeMI Technologies asked a question that if you do a text search on a database for the word “Python” and there are no computer-related books with that title, the search will show books related to Python snakes. But with a vector database like Weaviate, the search can be a semantic search instead of a traditional text-based search. Besides showing how to perform your first semantic search with the vector database Weaviate, Laura covered other functionalities of Weaviate, like multi-modal search, data classification, connecting custom ML models, etc.</p>
<p><img src="/assets/images/2022/stackconf-laura-talk.jpg" alt="Laura Ham talk" /></p>
<p align="center">
Laura Ham talk
</p>
<h2 id="reflecting-back">Reflecting back</h2>
<p><img src="/assets/images/2022/stackconf-dewan-markus.jpg" alt="Dewan with Markus, the host and conference organizer" /></p>
<p align="center">
Dewan with Markus, the host and conference organizer
</p>
<p>StackConf and a few other in-person conferences have been a great change after more than two years of virtual conferences. The confused looks or nodding of heads from the audience, the hallway chats, and great food make in-person conferences like StackConf a great success. I really hope that the flight delays and cancellations don’t become killjoys to the excitements of in-person conferences.</p>Dewan AhmedLast month I travelled across the pond to attend and give a talk at StackConf EU 2022 - an open-source infrastructure-focused conference. After two virtual events in 2020 and 2021, the conference took place live this year in the capital city of Berlin. The two-day conference was packed with exciting talks from industry leaders in the areas of cloud, DevOps, databases, machine learning, and other areas. You can check out the conference archive for recordings of all the talks. In this blog, I write about my favorite talks and moments from StackConf.