First, I began contemplating how to increase engagement with my open-source project.Ā Why?Ā Because:
- Developers play a pivotal role in adopting and integrating your product into their projects.
- Engaged developers, who have a positive experience with your product, can become influential advocates.
- They are more likely to explore the extensibility options and customization capabilities of your product.
- Furthermore, engaged developers can offer valuable feedback, suggestions, and bug reports.
- Ultimately, they might actively participate in your product's open-source community, contributing code, reporting issues, and collaborating on its development.
Their contributions can expedite the pace of innovation, foster a sense of ownership and community, and trigger a network effect that entices more developers to get involved.
As a result, I decided to create an appealingĀ README.
Create a Good Readme
It should be able to convey what your project is capable of doing, how to install and work with the project, how to contribute, and more. It also maintains structured information about the product and its implementation details.
To avoid overloading the mainĀ README, there are several child files created to provide additional details:
CodeDocumentation.md Ā - Describes how to document the code.CodeStyle.md Ā - Describes the code style.Constraints.md Ā - Describes the solution constraints.Dependencies.md Ā - Describes the tools and libraries used for product development.DependenciesOld.md Ā - Describes the old tools and libraries that were used for product development.FunctionalView.md Ā - Shows and describes the functional view.QualityAttributes.md Ā - Describes the product's Quality Attributes.
Furthermore, my **README starts with the product logo.
Badges
TheĀ READMEĀ then proceeds to badge chapters that prove helpful for developers. These sections include:
- Common(Repository stars, contributors, followers, sponsors, and Twitter URL)
- Release(Latest release version, release date, and number of downloads)
- Code Statistics(Build flow status, GitHub commit activity, GitHub's latest commit, and CodeFactor.io status)
- Issues and Pull Requests(GitHub issues, closed issues, pull requests, and closed pull requests)
- Repository Statistics(GitHub top language, count of languages, and repository size)
- Documentation(Roadmap, Discussions, License, and Main README)
There are three different types of badges based on their implementation approach:
- Implemented by GitHub, displayed as:Ā
GitHub Badge - Implemented by img.shields.io, displayed as:Ā
Badge - Implemented byĀ
www.codefactor.io , displayed as:ĀBadge
Quick Links
Following this, theĀ READMEĀ transitions to theĀ
Capabilities and Description
The description ofĀ
Architecture Documentation
Subsequently, theĀ READMEĀ delves into the description ofĀ Architecture Documentation, encompassing the following chapters:
Software Architecture Requirements Software Architecture Views Tools , Libraries andĀProgramming Languages Licenses
For more detailed information, please refer to the designatedĀ
Code Style and Documentation
TheĀ READMEĀ then proceeds to expound uponĀ
Should you require further information, feel free to explore the section dedicated toĀ Code StyleĀ andĀ Documentation.
Implementation Status
Subsequently, I contemplated an effective means to monitor theĀ
- Implemented: This column denotes whether the requirement has been implemented, denoted as either "yes" or "no."
- Feature ID: This serves as an identifier originating from the project's features.
- Component: This field specifies the name of the corresponding component.
- File Names: Here, the file names are enumerated where the implementation pertaining to the requirement can be located.
- Description: This column furnishes a descriptive account of the functional requirement.
Contributing and Stay in Touch
In this section, I outline the various channels that individuals can utilize to contribute to the project's development. This includes information on how one can actively participate and offer their assistance.
Definitions, Acronyms, Abbreviations
Lastly, I provide an explanation ofĀ Definitions, Acronyms, and Abbreviations. Presented in a tabular format, this section comprises the following columns:
- Number
- Abbreviation or Acronym
- Definition
Project Status Tracking
In a broader perspective, monitoring the project's status holds immense significance for aĀ Delivery Manager. This practice ensures the triumph of the project by overseeing factors such as risk management, resource allocation, effective communication, and the ability to make well-informed decisions across the entirety of the project's lifecycle.
GitHub Projects
GitHub ProjectsĀ emerges as a tool dedicated to tracking project status in an online environment, seamlessly integrated into yourĀ GitHubĀ profile. Its user-friendly interface facilitates ease of use, and while it doesn't offer an extensive array of functions, it adeptly serves its purpose. Allow me to presentĀ
ProjectLibre
Despite the aforementioned options, the demand for a more sophisticated solution persisted. In light of this, my preference leaned towardsĀ
Despite its stature as a compact and cost-free application,Ā ProjectLibreĀ remarkably delivered everything essential for my needs.
Releasing the Code and Documentation
The release of the product is strategically planned to coincide with the readiness of a substantial portion of its functionality. Whenever a segment of the product's functionality is deemed ready for release, the creation or updating of the release branch ensues. This practice ensures that any added or updated product functionality is seamlessly integrated into the release branch.
Irrespective of adopting an incremental approach to the addition or update of product functions, it's pivotal to underscore that the resulting artifacts shall encompass the entirety of the product installation packages. This holds true even when releasing relatively minor components of functionality.
In adherence to this approach, the ensuing artifacts are generated:
- Documentation for the code, structured around doxy comments.
- Installation packages for the latest versions ofĀ Windows, Mac, and Linux.