Creating Effective ONDC Landscape
Creating effective ONDC Landscape
To support an effective technical landscape, this article provides an overview of the core principles of ONDC. It also highlights the best practices for onboarding NP(Network participants). Applying these technical principles shall help maintain the easiness of launching the business on the network. We also document your project or product or contributing to technical content in various settings, you can improve the quality of your work by following these best practices.
Effective feature is important in enhancing a user’s experience with ONDC. Good documentation is like a piece of the puzzle that makes everything click — the key for encouraging feature adoption.
Adopt clarity, conciseness, and consistency
These three Cs form the core principles of writing. They can take you a long way in producing quality documentation.
Clarity
- Use simple words and clear language. Keep in mind the audience, especially if it includes non-native English speakers.
- Be clear about who needs to perform the action. Writing in active voice is not strictly required. However, you should use it when you want to be clear about who needs to perform the action. For example, clarify whether a function is triggered by an event or if the user needs to explicitly call the function.
- To avoid ambiguity, specify pronouns clearly. Replace “it”, “this”, and “these” with proper nouns if they can refer to more than one thing in the given context.
- Aim for one idea per sentence to improve readability.
- Stick to one main idea per paragraph. Each sentence in a paragraph should logically connect to the one before it. Imagine if each sentence in a paragraph was a link in a chain. If you pick up the first link, the other links in the chain should follow, forming a continuous sequence. This is how the sentences should connect to each other, ensuring a seamless flow of a single idea.
Conciseness
Keep sentences short. This automatically increases the readability and clarity of your document. It also helps in quick comprehension. Long sentences can be more challenging to understand quickly due to their complex structures.
Based on common readability standards, aim for 15-20 words per sentence.
Consistency
Use the same terminology throughout your documentation to ensure a seamless reader experience. For example, if you start referring to “user agents” as browsers, stick with that term consistently. This avoids confusion that can arise from using words interchangeably, even when they share the same meaning.
Additionally, maintain consistent word casing and follow a uniform formatting style throughout your documentation. These practices not only enhance readability but also contribute to a professional presentation of your documentation.
Organize your content for maximum impact
Apply the same principles for organizing your content as you would for organizing your code: spend some time setting a clear goal and thinking about the desired structure for your documentation. Ensure that each subsection contributes to this goal incrementally.
Start with an introduction
In the introduction, first describe the feature you’re documenting. Next, set the context by explaining why learning about the feature would be beneficial to the readers. This can include describing real-life scenarios where the feature can be useful. The more relevance you add to the topic, the easier it will be for readers to understand and engage with the content.
Progress logically
- In the introduction, first describe the feature you’re documenting. Next, set the context by explaining why learning about the feature would be beneficial to the readers. This can include describing real-life scenarios where the feature can be useful. The more relevance you add to the topic, the easier it will be for readers to understand and engage with the content.
- Are there sufficient how-to guides or examples following the conceptual sections?
- Consider the flow of the content. Is it following a logical sequence — from one sentence to the next, from one paragraph to the next, and from one section to the next? Does each section logically build on the information presented previously, avoiding abrupt jumps or gaps in the content?
- What reader questions am I addressing with this sentence?
- Can I add a simplistic or real-life use case to explain this concept?
Proofread your writing
One aspect that cannot be stressed enough is the importance of self-reviewing and proofreading what you’ve written. Whether you’re creating a large document or a short paragraph, this step is crucial.
Taking the time to fully review your work will help you identify sections that don’t flow well or can be improved for clarity. During self-review, aim to spot and remove redundancy (repetition of ideas without adding value) and repetitiveness (overuse of words or phrases). These refinements will ensure your documentation is clear and coherent and conveys your ideas as intended.
Proofread and then take a break before you review again. Only then submit your work. While spell checkers can flag spelling errors, they might not flag incorrect use of words, such as an unintended use of “he” instead of “the”. It’s best to take a break and return with fresh eyes to catch any errors you might have missed. Pay close attention to identify inconsistencies in tone, style, tense, or formatting and make the necessary adjustments.
Summary
That’s it for this article. I hope you found these tips helpful as a quick refresher on technical writing best practices. Remember that learning how to create effective and easy-to-use documentation is an ongoing process. It starts with understanding your audience and the goals of your documentation. By applying these technical writing principles and tips, you’ll certainly be able to enhance the clarity and overall quality of your documentation.
