Import Adaptor Content To OpenFn Docs Site

This article outlines the process of importing adaptor and wiki content into the OpenFn documentation site. Currently, the primary source of information and guidance on contributing to the Open Source Project is maintained by @josephjclark and other contributors through Markdown files located in the OpenFn adaptors repository. This guide will walk you through how to integrate this valuable content into the official documentation.

The Need for Integration

Previously, users were directed to the Wiki for guidance on building adaptors. However, this resource has become outdated as most of the content has been migrated and updated. To ensure users have access to the most current and comprehensive information, it's crucial to surface the latest guidance on building adaptors directly within the 'Contribution' section of the OpenFn documentation site. This integration will streamline the user experience and make it easier for contributors to find the resources they need.

Goal

The primary goal is to create a new 'Adaptors' section within the 'Contribute' area of the Docs Site. This section will serve as a centralized hub for all information related to adaptor development, ensuring that contributors have easy access to the latest guidelines and best practices.

Implementation Plan

To achieve this goal, the new 'Adaptors' section will be structured into several sub-sections, each addressing a specific aspect of adaptor development. Here’s a detailed breakdown of the proposed structure:

1. Adaptors 101 Landing Page

This landing page will serve as an introduction to adaptor development within the OpenFn ecosystem. It is crucial that this page provides a high-level overview, setting the stage for more detailed information in the subsequent sub-sections. The content for this page will be pulled directly from the 'Introduction' page of the Adaptors documentation, located here: Adaptors Introduction.

Content Sourcing and Updates

The content for this landing page must be dynamic, reflecting the latest information available. Regular updates should be sourced from the official 'Introduction' page to ensure consistency and accuracy. This approach ensures that contributors always have access to the most current information, reducing confusion and streamlining the development process.

2. Build a New Adaptor

This sub-section will provide a beginner's guide to creating a new adaptor. This is a critical resource for developers who are new to the OpenFn platform and want to contribute by building adaptors. The content will be sourced from the build-a-new-adaptor.md file in the GitHub repository: Build a New Adaptor Guide.

Comprehensive Guidance

This guide should cover all the fundamental steps involved in creating an adaptor, from setting up the development environment to writing the first lines of code. Clear, concise instructions and practical examples are essential to make this guide accessible to developers of all skill levels. The focus should be on providing a smooth onboarding experience for new contributors.

3. Useful Commands

This section will list and explain useful CLI commands provided within the repository. Command-line tools are an integral part of the development workflow, and this section aims to provide a quick reference for developers. The content will be sourced from the commands.md file: Useful Commands.

Practical Reference

Each command should be clearly explained, with examples of how to use it in different scenarios. This section should be structured for easy navigation, allowing developers to quickly find the command they need. Providing a practical reference for commonly used commands can significantly improve developer productivity.

4. Best Practice

This sub-section will outline the best practices for creating an adaptor. Adhering to best practices is crucial for maintaining code quality and ensuring consistency across all adaptors. The content will be sourced from the best-practice.md file: Best Practice Guide.

Quality and Consistency

This guide should cover various aspects of adaptor development, including coding standards, error handling, and performance optimization. Emphasizing the importance of maintainability and scalability can help developers write more robust and efficient adaptors. Regular updates to this section are necessary to reflect evolving best practices in the OpenFn community.

5. Documentation Guide

This section will provide advice, style guidelines, and best practices for writing documentation and JSDocs. High-quality documentation is essential for the usability and maintainability of adaptors. The content will be sourced from the docs.md file: Documentation Guide.

Clarity and Accuracy

This guide should cover the key elements of effective documentation, such as clear explanations, relevant examples, and proper formatting. It should also emphasize the importance of keeping documentation up-to-date with the latest changes in the codebase. Providing a comprehensive documentation guide helps ensure that adaptors are well-documented and easy to understand.

6. FHIR Adaptors

This sub-section will provide details about the FHIR adaptor generator. FHIR (Fast Healthcare Interoperability Resources) is a widely used standard in healthcare, and this section aims to provide specific guidance for developing FHIR adaptors. The content will be sourced from the fhir.md file: FHIR Adaptors Details.

Specialized Guidance

This guide should cover the specific challenges and considerations involved in developing FHIR adaptors, such as data mapping, security, and compliance. Providing specialized guidance for FHIR adaptors can help developers create interoperable solutions that meet the needs of the healthcare industry.

7. Magic Functions

This section will explain what Magic Functions and Metadata are, and how they work within the OpenFn platform. Understanding Magic Functions is crucial for leveraging the full power of the platform. The content will be sourced from the magic-functions.md file: Magic Functions Explained.

Core Concepts

This guide should provide a clear and concise explanation of Magic Functions and Metadata, including their purpose, usage, and best practices. Real-world examples can help developers understand how to effectively use these features in their adaptors. A thorough understanding of Magic Functions can significantly enhance the functionality and flexibility of adaptors.

8. Unit Test Guide

This sub-section will provide a guide to unit tests in general, and the principles of testing for this repository. Unit testing is a critical part of the development process, ensuring that adaptors function correctly and reliably. The content will be sourced from the unit-test-guide.md file: Unit Test Guide.

Ensuring Reliability

This guide should cover the basics of unit testing, as well as the specific testing requirements and best practices for the OpenFn platform. Providing clear examples of how to write effective unit tests can help developers create more robust and reliable adaptors. Regular unit testing helps prevent bugs and ensures the long-term stability of the codebase.

Acceptance Criteria

To ensure the successful implementation of this project, the following acceptance criteria must be met:

1. New 'Adaptors' Section: When viewing the 'Contribute' section of the Docs Site, users should see a new section labeled 'Adaptors'.
2. Sub-Sections Visibility: Expanding the 'Adaptors' section should reveal all the sub-sections listed above: Build a new Adaptor; Useful Commands; Best Practice; Documentation Guide; FHIR Adaptors; Magic Functions; Unit Test Guide.
3. Content Accuracy: Clicking into each sub-section should display the latest version of the content stored in the corresponding Markdown files in the OpenFn adaptors repository.
4. Dynamic Updates: Any updates made to the Markdown files should be reflected in the Docs site, ensuring that the documentation remains current.

Conclusion

Importing the adaptor and wiki content into the OpenFn documentation site is a crucial step in providing a comprehensive and up-to-date resource for contributors. By organizing the content into clear, well-defined sections, we can ensure that developers have easy access to the information they need to build high-quality adaptors. This integration will enhance the overall developer experience and contribute to the continued growth and success of the OpenFn platform.

For more information on contributing to open-source projects, you can visit GitHub's Open Source Guides.