OSS Documentation Assistant
Table of Contents
The Open Source Software (OSS) community underpins countless businesses worldwide, with over 50% of Fortune 500 companies relying on it for their workflows—a number poised to grow as more projects gain traction. However, this growth hinges on consistent feature development, which is challenging without more developers. Research by Ravi Sen, Siddhartha S. Singh, and Sharad Borle found that adding 10 developers to a project increases average subscribers by 5.65%, demonstrating a clear link between developer engagement and user adoption.
Given this, OSS projects must prioritize lowering barriers to entry and welcoming community contributions—the very ethos of OSS. Unfortunately, this is far from the norm. A 2014 study revealed that only 5.4% of 2,000 projects included architectural documentation, a crucial tool for scaling and collaboration. While many OSS projects have achieved remarkable growth, more widespread emphasis on software architecture documentation could drive success for countless lesser-known initiatives.
Effective documentation should guide users and developers through a project’s purpose, workflow, and future direction. A basic overview and installation guide are insufficient; developers need clear navigation of the source code and actionable tasks, while users benefit from insight into future plans and transparent communication channels.
This README aims to set a standard for OSS documentation, improving project accessibility and fostering contributions from both the community and aspiring developers.
Listing the major tools and languages used in the project helps it appear in filtered search results for any included library. Additionally, it allows developers to quickly identify whether a library they are proficient in is part of the project. Refer to the "Markdown Links and Images" section of the HTML version of this file to learn how these logo URLs are created.
This section should walk through installation on various operating systems as well as any installation options. The readability of this section will make or break whether someone will use the project, since this section is often the most looked at section
Ensure you have git, python (and presumably pip too). Best bet, download the official release for your platform (Operating System) from the provided homepages and their download section. On Windows, your best bet is to use the resulting Git Bash application that will become available after installing git.
Comfirm prerequisites by running the following command:
git --version && python --version && pip --versionDownload and navigate into the repository:
git clone https://github.com/montymi/ClearDocs/ && cd ClearDocsConvert contents of README.md to the raw form, copy file and paste into your project. (Boring ik, that is a WIP for after the holidays 😊.)
Users are much more likely to use and test a project if they can quickly determine how best to use the software and whether or not it really is what they are looking for. Clear usage examples also give incoming developers a chance to better understand the code and its intended use.
Here is an example from this project that hopefully won't stand for very long:
Manually convert the section information to fit project, including the URLs for tools, tests, and contact cards which need to be found, added, and called.
TODO; Check Tasks for updates coming soon!
Less than 6% of GitHub projects include documentation or diagrams about the software's architecture. Since larger projects can often have a very convoluted source code structure, diagrams are the ideal method of displaying the flow of the project.
ClearDocs
├── README.md
├── src
│ ├── __init__.py
│ ├── cli.py
│ └── utils.py
└── docs
├── index.md
├── installation.md
├── usage.md
├── configuration.md
├── contributing.md
├── api
│ └── overview.md
├── tutorials
│ ├── getting_started.md
│ └── advanced_features.md
└── references
├── glossary.md
└── faq.md
By publicly displaying the to-do list of the project, users are able to see any feature that is nearing implementation. The list also allows new developers to quickly find potential tasks for them to complete which is an ideal way to familiarize them with the source code and to continue to make commits.
- Emphasize 5.4% of projects section (speculation about what the observable differences would be if it were a higher figure)
- Fix "Built With" logos section
- Revision at the sentence level
- Center architecture image
- Add Author's Note
- Fix some links
- Change code examples to be ClearDocs project
- Add CLI capabilities for README creation
- Improve CLI with docs/ folder
- Automate deployment to gh-pages through CLI
- package and post to PIP
See the open issues for a full list of issues and proposed features.
Contributions are, in my opinion, the greatest part of OSS and are what will be the key to continuing the growth of the community. One of the main goals of this README is to facilitate contributions of potential developers. In this section, developers must be sure to lay out any coding styling choices that they may have so that the source code can remain as uniform as possible. One such project that has an immpressive contributions page is htop by htop-dev who point all potential incoming contributors to their style guide
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Documentation must include a license section in which the type of license and a link or reference to the full license in the repository is given.
Distributed under the GPL-3.0 License. See LICENSE.txt for more information.
Michael Montanaro
Use this space to list any resources used or that may be helpful in understanding the project