{"id":8799,"date":"2023-08-29T19:21:13","date_gmt":"2023-08-29T13:51:13","guid":{"rendered":"https:\/\/razorpay.com\/learn\/?p=8799"},"modified":"2025-03-07T14:15:11","modified_gmt":"2025-03-07T08:45:11","slug":"empowering-coders-with-developer-documentation","status":"publish","type":"post","link":"https:\/\/razorpay.com\/learn\/empowering-coders-with-developer-documentation\/","title":{"rendered":"Empowering Coders with Developer Documentation"},"content":{"rendered":"<p><span style=\"font-weight: 400;\">Before starting to write on Developer Documentation, I searched online for the definition of a Developer and found a couple of funny ones.<\/span><\/p>\n<h6><i><span style=\"font-weight: 400;\">Developer:<\/span><\/i><\/h6>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><i><span style=\"font-weight: 400;\">An organism that converts coffee and pizza into code.<\/span><\/i><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><i><span style=\"font-weight: 400;\">Someone who solves a problem you didn&#8217;t know you had in a way you didn&#8217;t understand.<\/span><\/i><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">But jokes apart. Who is a developer? What are their traits?<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Developers are problem solvers. They analyse complex problems and deliver creative solutions. We have some fantastic software applications (including this one) thanks to them.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">As tech writers, one of the major audience segments we write for is the developer community. And writing for developers is slightly different than writing for other users. In this blog, we&#8217;ll explore this thought and look at some tips to remember when creating content for this audience segment.<\/span><\/p>\n<h1><span style=\"font-weight: 400;\">Developers vs. Other Users<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">While both developers and other non-developer users, such as business decision-makers and non-technical users, seek information, they seek different types of information.<\/span><\/p>\n<h2><b>Content Requirements<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Developers have specific documentation requirements that emphasise syntax, workflows, and customisation. Developers highly value clarity and conciseness and frequently skim for targeted information. Meanwhile, non-developers prefer ease of understanding, practical application, and a broader context. They want content with non-technical language, real-world examples, and relatable scenarios.<\/span><\/p>\n<h2><b>Documentation Type<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Developers need multiple types of documentation:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Integration Documents: SDK Guides help developers integrate their systems with vendor systems.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Reference Materials: API Reference guides with exhaustive sample codes in multiple languages.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Troubleshooting Guides &amp; Error Lists: Content that helps developers when they are mired in issues and need quick solutions to move ahead.<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">On the other hand, business decision-makers seek content that would help them learn about a product&#8217;s features and benefits. The non-technical users want procedural instructions enabling them to take UI-based actions.<\/span><\/p>\n<h2><b>Technical Knowledge<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Developers are far more tech-savvy than other audience segments (business decision-makers and non-technical users). They can easily understand jargon and terms others find difficult to relate to. For example, JSON response is something developers understand. However, non-technical users would not be able to understand what that means readily.<\/span><\/p>\n<h2><b>Testing Tracks<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">While business decision-makers seek product demos and non-technical users like to watch video materials to understand the software better, developers prefer to test the content by safely carrying out experiments in sandbox environments. Adding such playgrounds has proven to be a value addition for developers as they do not have to exert much effort in setting up complex systems just to try out APIs. For example, <a href=\"https:\/\/www.postman.com\/\" target=\"_blank\" rel=\"noopener\">Postman Workspace<\/a> is one such popular API playground.<\/span><\/p>\n<h1><span style=\"font-weight: 400;\">Authoring Process<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">Tech Writing for Developers largely follows the same process as any other software documentation. We must research the audience, understand their needs and craft content that solves their queries.<\/span><b><\/b><\/p>\n<h2><b>1. Understanding the Audience<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">This is the primary step, wherein writers must understand the target audience. Developers come with different proficiency levels and experience, from newly minted engineers to industry veterans. Tech Writers can talk to some developers who have recently integrated with their products or the sales\/product team to understand the audience mix. Once this data is available, we can craft the content per their needs. Read more about <a href=\"https:\/\/razorpay.com\/learn\/guide-to-audience-research-tech-writing\/\">Audience Research<\/a>.<\/span><b><\/b><\/p>\n<h2><b>2. Structuring the Developer Docs<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Developers have been viewing documentation from various sources &#8211; other product companies, your competitors and so on. Therefore, they come to the documentation expecting a certain structure. For example, an API Reference Guide should have the following structure for developers to find their way and start coding swiftly.<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">API Overview<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">API Authentication Method<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Endpoints<\/span>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Overview<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Use Cases<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Request and Response Sample Codes<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Error Codes &amp; Other Troubleshooting information<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Parameter Descriptions<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"2\"><span style=\"font-weight: 400;\">Links to API Playground<\/span><b><\/b><b><\/b><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<figure id=\"attachment_8800\" aria-describedby=\"caption-attachment-8800\" style=\"width: 2880px\" class=\"wp-caption alignnone\"><img decoding=\"async\" class=\"wp-image-8800 size-full\" src=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM.png\" alt=\"A screenshot of a Developer Documentation page (API page)\" width=\"2880\" height=\"1438\" srcset=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM.png 2880w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM-300x150.png 300w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM-1024x511.png 1024w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM-1536x767.png 1536w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.36.23-PM-2048x1023.png 2048w\" sizes=\"(max-width: 2880px) 100vw, 2880px\" \/><figcaption id=\"caption-attachment-8800\" class=\"wp-caption-text\">A screenshot of a Developer Documentation page (API)<\/figcaption><\/figure>\n<h2><b>3. Simple Language, Clear Instructions<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">One should consider what kind of information developers prefer. Do they seek more context? Would more diagrams help? Developers do not like to read a lot of content; they appreciate brevity. But conciseness should not come at the cost of context. Hence, it is best to write simple, short instructions which convey the necessary information. Adding diagrams and other visual aids wherever needed enriches the content.<\/span><b><\/b><\/p>\n<h2><b>4. Internal Review<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">After the first draft is ready, writers should send it out with the relevant teams &#8211; product, tech and integrations\/support- for internal review. The integrations\/support team can do the UAT for the documentation. They can use the documentation as the base and conduct a short testing round to ensure the document accurately captures all the relevant details. Based on these findings, the writers can improve the content by adding more sample codes, use cases, etc.<\/span><br \/>\n<b><\/b><\/p>\n<h2><b>5. Go-Live and Feedback Collection<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Once the documentation is published, it is not the end of the road. Writers should constantly measure the market feedback. Are developers responding well to the documentation, or are there any misses? What could be added\/done better?<\/span><\/p>\n<p><span style=\"font-weight: 400;\">At Razorpay, we have integrated user feedback modules in the <a href=\"https:\/\/razorpay.com\/docs\/api\/\">API Documentation<\/a> so that developers can swiftly provide suggestions and recommendations for documentation improvements.<\/span><\/p>\n<figure id=\"attachment_8801\" aria-describedby=\"caption-attachment-8801\" style=\"width: 2880px\" class=\"wp-caption alignnone\"><img decoding=\"async\" class=\"wp-image-8801 size-full\" src=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM.png\" alt=\"Feedback Collection page to collect Developer feedback\" width=\"2880\" height=\"1440\" srcset=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM.png 2880w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM-300x150.png 300w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM-1024x512.png 1024w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM-1536x768.png 1536w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-29-at-6.35.55-PM-2048x1024.png 2048w\" sizes=\"(max-width: 2880px) 100vw, 2880px\" \/><figcaption id=\"caption-attachment-8801\" class=\"wp-caption-text\">Feedback Collection Module in Razorpay Docs pages<\/figcaption><\/figure>\n<p><span style=\"font-weight: 400;\">We also conduct developer interviews wherein we ask users to try our APIs on the spot and provide their feedback on the user journey. Read more on Razorpay&#8217;s <a href=\"https:\/\/razorpay.com\/learn\/user-feedback\/\">User Feedback<\/a> initiative here. All these measures have helped us understand the developer\u2019s perception of our documentation and helped us improve them further.<\/span><\/p>\n<h1><span style=\"font-weight: 400;\">Conclusion<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">Tech Writers can consider the above points to create technical documentation that empowers developers to engage with the software effectively. This will ensure a positive user experience and help build a loyal developer community.<br \/>\n<img decoding=\"async\" class=\"wp-image-16394 aligncenter\" src=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Banner-Image-4-300x135.png\" alt=\"\" width=\"531\" height=\"239\" srcset=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Banner-Image-4-300x135.png 300w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Banner-Image-4-1024x459.png 1024w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Banner-Image-4-768x344.png 768w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Banner-Image-4.png 1200w\" sizes=\"(max-width: 531px) 100vw, 531px\" \/><br \/>\n<\/span><\/p>\n<div style=\"text-align: center;\"><a style=\"border-radius: 3px; background: #528FF0; padding: 15px; font-weight: 600; cursor: pointer; text-decoration: none; color: white;\" href=\"https:\/\/dashboard.razorpay.com\/signup?r=partner&amp;\">Become a partner now!<\/a><\/div>\n","protected":false},"excerpt":{"rendered":"<p>Before starting to write on Developer Documentation, I searched online for the definition of a Developer and found a couple of funny ones. Developer: An organism that converts coffee and pizza into code. Someone who solves a problem you didn&#8217;t know you had in a way you didn&#8217;t understand. But jokes apart. Who is a<\/p>\n","protected":false},"author":151156543,"featured_media":8802,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3606],"tags":[3613],"class_list":{"0":"post-8799","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","7":"category-tech-writing","8":"tag-technical-writing"},"_links":{"self":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8799","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/users\/151156543"}],"replies":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/comments?post=8799"}],"version-history":[{"count":9,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8799\/revisions"}],"predecessor-version":[{"id":16395,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8799\/revisions\/16395"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/media\/8802"}],"wp:attachment":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/media?parent=8799"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/categories?post=8799"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/tags?post=8799"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}