README-MKC-Standard

A markdown file template of README.md of GitHub repositories for desktop and mobile applications. It focuses on being informative, consistent design and well-structured content. This template tries to avoid HTML syntax and maintain markdown syntax throughout the template to keep the code cleaner and maintainable. A set of images/screenshot resolutions and other standards are recommended below to maintain a consistent layout while trying to make screenshots readable for most screen sizes.

Table of Contents

• Standards
• Usage
• License
• Acknowledgments

Standards

Content Format

The following are recommendations on how to write and structure text content:

• Use proofreading tools to identify errors in grammar, punctuation and spelling if in doubt.
• Be consistent on how you compose sentences such as using the same starting words, where to use declarative/imperative sentences and sentence complexity.
• Read your sentences several times to judge whether improvement is required.
• Change, remove, add or rearrange this template's sections to fit to preferred style.
• When changing or adding a section title, keep the section title as short as possible with a maximum of three words.

Image Handling

The following are recommendations on how to consistently display images/screenshots:

• The width resolution is recommended to be followed to maintain a consistent design and avoid images from stacking vertically.
• The height resolution can vary, but is it recommended to keep every image/screenshot resolution identical in a single row.
• If there is a large gap between images/screenshots in a single row, try to order them from tallest to smallest.

Image Resolutions

• Project Logo - width: 28px

• Single - width: 640px
• Ideal for promotional image and application main screen.
• Recommended for landscape screenshots.

 

• Double - width: 400px
• Ideal for main features to keep them in one place.
• Recommended for landscape screenshots.

   

• Triple - width: 264px
• Ideal for main features to keep them in one place.
• Recommended only for portrait screenshots.
• Not recommended for landscape screenshots.

Markdown Syntax Convention

The following are recommendations on how to properly write markdown syntax:

• Use # only for top heading.
• Use ## for the section title.
• Use ### for sub-section title.
• Use https://img.shields.io/badge/<Environment>-<Type>-<COLOR> for project badge (e.g. )
• Use <img src="https://github.com/username/repository/blob/hash/docs/file.png" width="28" alt="alt-text" to control the width of displayed images.
• Use [<ref-name>]: <link> link reference (located at the bottom of the markdowns) to improved link reusability and maintainability if necessary.
• Use ![<alt desc>][<ref-name>] link reference (from the bottom) to display the image or highlight the link (remove the !).
• Use   to add horizontal spacing between images.
• Use **[<tool/contributor name>][<ref-name>]**: For <contribution> for acknowledgments.
• Add single empty space between sections.
• Add single empty space between groups of references at the bottom.

Usage

1. Copy the README_TEMPLATE.md file to your GitHub repository.
2. Rename the README_TEMPLATE.md into README.md.
3. Create a docs folder in the same directory and store the images that will be use by the README.md file.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Shields.io: For badges.