Skip to content

Latest commit

 

History

History

practices

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
16personalities.md
16personalities.md
 
 
Developer_portal.md
Developer_portal.md
 
 
Git.md
Git.md
 
 
agile_events.md
agile_events.md
 
 
api_authentication.md
api_authentication.md
 
 
api_first_development.md
api_first_development.md
 
 
automated_deployment.md
automated_deployment.md
 
 
backlog_cleanup.md
backlog_cleanup.md
 
 
bus_factor.md
bus_factor.md
 
 
clickable_prototype.md
clickable_prototype.md
 
 
code_coverage.md
code_coverage.md
 
 
code_review.md
code_review.md
 
 
commit_naming_rules.md
commit_naming_rules.md
 
 
continuous_delivery.md
continuous_delivery.md
 
 
continuous_integration.md
continuous_integration.md
 
 
cookie_settings.md
cookie_settings.md
 
 
design_sprint.md
design_sprint.md
 
 
design_thinking.md
design_thinking.md
 
 
devops.md
devops.md
 
 
differentiation_strategy.md
differentiation_strategy.md
 
 
dockerizing.md
dockerizing.md
 
 
documentation.md
documentation.md
 
 
documentation_testing.md
documentation_testing.md
 
 
effective_team_communication.md
effective_team_communication.md
 
 
epics.md
epics.md
 
 
extreme_ownership.md
extreme_ownership.md
 
 
extreme_programming.md
extreme_programming.md
 
 
fail_fast.md
fail_fast.md
 
 
feedback.md
feedback.md
 
 
gallup.md
gallup.md
 
 
git_flow.md
git_flow.md
 
 
gitignore.md
gitignore.md
 
 
good_developer_experience.md
good_developer_experience.md
 
 
handover.md
handover.md
 
 
home-office.md
home-office.md
 
 
icebreaker.md
icebreaker.md
 
 
infrastructure_as_code.md
infrastructure_as_code.md
 
 
integration_testing.md
integration_testing.md
 
 
javascript-front-end-build-tools.md
javascript-front-end-build-tools.md
 
 
jtbd-framework.md
jtbd-framework.md
 
 
kafka.md
kafka.md
 
 
kanban.md
kanban.md
 
 
kiss.md
kiss.md
 
 
lean_canvas.md
lean_canvas.md
 
 
license_in_repository.md
license_in_repository.md
 
 
linting.md
linting.md
 
 
lock-file.md
lock-file.md
 
 
meaningful-meetings.md
meaningful-meetings.md
 
 
mentoring.md
mentoring.md
 
 
mvp.md
mvp.md
 
 
okr.md
okr.md
 
 
operations_logbook.md
operations_logbook.md
 
 
package_management.md
package_management.md
 
 
pair_programming.md
pair_programming.md
 
 
penetration_testing.md
penetration_testing.md
 
 
performance_testing.md
performance_testing.md
 
 
pilot_project.md
pilot_project.md
 
 
product_backlog.md
product_backlog.md
 
 
product_backlog_refinement.md
product_backlog_refinement.md
 
 
product_owner.md
product_owner.md
 
 
proper_bug_reporting.md
proper_bug_reporting.md
 
 
pull_requests.md
pull_requests.md
 
 
readme.md
readme.md
 
 
refactoring.md
refactoring.md
 
 
release_management.md
release_management.md
 
 
respectful_code_reviews.md
respectful_code_reviews.md
 
 
responsibility.md
responsibility.md
 
 
rest_api.md
rest_api.md
 
 
retrospective.md
retrospective.md
 
 
risk_analysis.md
risk_analysis.md
 
 
runbook.md
runbook.md
 
 
scrum.md
scrum.md
 
 
semantic_versioning.md
semantic_versioning.md
 
 
smart_goals.md
smart_goals.md
 
 
smoke_testing.md
smoke_testing.md
 
 
software_development_kit.md
software_development_kit.md
 
 
software_documentation.md
software_documentation.md
 
 
software_portability.md
software_portability.md
 
 
solid_principle.md
solid_principle.md
 
 
staged_rollout.md
staged_rollout.md
 
 
start_as_a_coder.md
start_as_a_coder.md
 
 
story_points.md
story_points.md
 
 
team_culture.md
team_culture.md
 
 
team_lead.md
team_lead.md
 
 
team_roles_definition.md
team_roles_definition.md
 
 
tech_lead.md
tech_lead.md
 
 
tech_writing.md
tech_writing.md
 
 
test_cards.md
test_cards.md
 
 
unit_testing.md
unit_testing.md
 
 
updating_the_dependencies.md
updating_the_dependencies.md
 
 
user_stories.md
user_stories.md
 
 
ux-testing-goals.md
ux-testing-goals.md
 
 
ux_prototypes.md
ux_prototypes.md
 
 
ux_strategy.md
ux_strategy.md
 
 
value_proposition.md
value_proposition.md
 
 
vision.md
vision.md
 
 
waterfall.md
waterfall.md
 
 
wireframing.md
wireframing.md
 
 
yagni_principle.md
yagni_principle.md
 
 

readme.md

slug stages short_description tags keywords author_github_username
readme
development
A README is a text file that contains important information about the product. It is the first thing the user sees in the directory of the product. It helps the user to understand what does the product do and how to use it.
software documentation
product
documentation
information
description
introduction
installation
writing
user story
readme
introduction
directory
badge
installation
contribution
directory
documentation
readme
prokopsimek

README

TL;DR

The first thing everyone sees in your product directory is README - an introduction of the product to a user. Make it thorough but simple, add every important information, and keep it updated.

What Is a README

A README is a text file that introduces a product to a user. It contains information that explains why the product is useful. It also ensures that the user knows how to use the product. A README file is usually the first thing the user sees in the directory of the product. It is most commonly written in a Markdown, which is a lightweight markup language with plain text format (for more information, see Wikipedia: Markdown).

A README file typically includes (at least) some of the following sections:

  • Name
  • Description What does the product do? Why is the product useful?
  • Badges Badges contain metadata that show that the project is taken care of.
  • Visuals Sometimes it is useful to add some screenshots or videos.
  • Installation instructions How to install the product?
  • Operating instructions How to use the product? Provide examples.
  • Support/troubleshooting Where can the user get help with the product?
  • Roadmap Ideas for future releases.
  • Contributing Are you open to contributions? In what conditions?
  • Authors and acknowledgment Who maintains and contributes to the project? Acknowledge the authors and maintainers.
  • Copyright and licensing information
  • Known bugs
  • Changelog (for developers) A changelog is a record of all the major changes made to the product.

Why You Might Want the README

README contains all the important information about your product. It answers the basic questions users may have and provides them with the information where to find more answers. A good README ensures that the other team members, product users, stakeholders, and others are able to understand what is your product about. A great README makes your product exceptional and gets the users’ attention. Without a README people do not have a chance to understand your product, no matter how great it is.

Issues the README Solves

How to Implement the README

  1. Start writing the README before you publish your product. README should be the first file you create.
  2. Put it in the top level directory.
  3. It is recommended to use Markdown language. Keep the format simple.
  4. Make it thorough but simple. Use short sentences and paragraphs but do not miss any important information.
  5. Keep it updated.
  6. Use examples.
  7. Link to other places if the data is too large or sensitive to keep it in README.

Common Pitfalls of the README

  • It is not being updated regularly.
  • It is too short or too long.
  • The maintainer is not mentioned - the support is missing.
  • It is not part of the depository and, therefore, difficult to find. Developers are used to looking for README in the root.

Resources for the README