Documentation Files in Markdown Format 📄

Every package can contain two documentation files: README.md and CHANGELOG.md. These files serve as the primary sources of information for users, providing insights into what the package does, how to use it, and its historical changes. The content of these files is written in Markdown, a lightweight and easy-to-use syntax for styling text.

What is Markdown?

Markdown is a text-to-HTML conversion tool, allowing writers to format their content using plain text. Its syntax is intuitive, making it easy to learn, even for those unfamiliar with HTML. With Markdown, you can easily apply styles like bold, italics, links, and lists without diving deep into complex coding structures.

For a comprehensive guide on Markdown and its various features, click here.

README.md 📖

The README.md file serves as the primary introduction to your package. Displayed on the main package page, it provides an overview of what the package does, how to set it up, and its usage.

Structure:

A typical README.md structure might look like:

# Package Name

A concise introduction or description of your package.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)

## Installation

Instructions on setting up the package, which could include terminal commands, dependencies, or specific configurations.

## Usage

Details demonstrating the package's functionality and its different features.

## Contributing

Steps or guidelines for those interested in contributing to the project.

Tips:

  • Ensure clarity in your description to improve user experience.
  • Incorporate visual aids, like screenshots or GIFs, for better understanding.
  • Structure is key. A well-organized README.md can significantly enhance user adoption rates.

CHANGELOG.md 🔄

The CHANGELOG.md offers a detailed historical record of the package. Documenting modifications, additions, removals, and fixes for each version, its content is showcased per-version on the package's version overview page.

Structure:

A standard CHANGELOG.md might look like:

# Changelog [1.0.1] - 2023-09-15

### Added
- New feature for enhanced performance.

### Changed
- Updated algorithm for better efficiency.

### Deprecated
- A method due to redundancy.

### Removed
- An old module.

### Fixed
- Resolved issues and bug fixes.

Tips:

  • Update the changelog consistently with every version release.
  • Clarity is crucial; ensure your descriptions are concise and easily understandable.
  • A consistent format aids users in effectively tracking changes.

Note: Including both README.md and CHANGELOG.md, while optional, is highly recommended. These files provide users with a clearer understanding of your package, promoting trust and usage.