User:TBurmeister (WMF)/Sandbox/Tool readme template
This is a basic documentation template for tools. It is available in two formats:
- Markdown: to copy and use as a template for a README file in your project's code repository.
- Wikitext: to copy and use on a wiki page that functions as your project's primary documentation landing page.
Wikitext
[edit]== {TOOL_NAME} ==
One sentence that describes what the tool does.
Example:
__TOC__
''If your README is short, you can remove the table of contents.''
== About {TOOL_NAME} ==
''Your goal in this section is to enable your reader to quickly assess whether this tool might help them accomplish their task, or if it is not right for them.''
Project status: on one line, indicate whether you are actively maintaining this tool, or if it is on hold or abandoned.
First paragraph:
* What does this tool help its users do?
* What problem(s) does the tool solve? Why did you build it?
* Why should someone use it?
Second paragraph:
* What are the main technologies the tool uses?
* Does the user need to know any programming languages or have certain technical skills to use it?
* Are there pieces of functionality that a user might expect, but which are not implemented?
* Why might someone not want to, or not be able to, use the tool?
Example:
== User guide ==
Write down the 3-5 most important tasks that users of your tool will do. Each of those tasks is a section of your user guide. Follow the basic user guide template to fill in those sections.
Before you create screenshots or videos to show users how to use your tool, consider the stability of your code. Visual aids can quickly become outdated and confusing if your tool's appearance or functionality changes, and keeping multimedia updated is more difficult than updating text. If it's too difficult to explain how to use your tool without screenshots or videos, consider how you might make your tool more user-friendly and intuitive. Good design requires less documentation!
== How to contribute ==
Do you welcome contributions from other developers? If so, explain what type of contributions are welcome to your project, and what your requirements are for accepting them.
=== Install and run {TOOL_NAME} ===
For others to contribute to your project, they need instructions to help them get started. For example, is there a script they should run or environment variables they must set? List the steps required to install and run your project locally, including any required dependencies. Provide a step-by-step description of how to set up and run the development environment.
Example:
== Credits ==
List any contributors and individuals, teams, or organizations who contributed to your development of this tool.
== License ==
Link to a file or page where you declare the license for your code. For more details, see [[wikitech:Help:Toolforge/Developing_successful_tools#Pick_a_license]].
Markdown
[edit]# {TOOL_NAME}
One sentence that describes what the tool does.
Example:
## About {TOOL_NAME}
Tip: Your goal in this section is to enable your reader to quickly assess whether this tool might help them accomplish their task, or if it is not right for them.
Project status: on one line, indicate whether you are actively maintaining this tool, or if it is on hold or abandoned.
First paragraph:
* What does this tool help its users do?
* What problem(s) does the tool solve? Why did you build it?
* Why should someone use it?
Second paragraph:
* What are the main technologies the tool uses?
* Does the user need to know any programming languages or have certain technical skills to use it?
* Are there pieces of functionality that a user might expect, but which are not implemented?
* Why might someone not want to, or not be able to, use the tool?
Example:
## User guide
Write down the 3-5 most important tasks that users of your tool will do. Each of those tasks is a section of your user guide. Follow the basic user guide template to fill in those sections.
### How to 1
### How to 2
### How to 4
Tip: Before you create screenshots or videos to show users how to use your tool, consider the stability of your code. Visual aids can quickly become outdated and confusing if your tool's appearance or functionality changes, and keeping multimedia updated is more difficult than updating text. If it's too difficult to explain how to use your tool without screenshots or videos, consider how you might make your tool more user-friendly and intuitive. Good design requires less documentation!
## How to contribute
Do you welcome contributions from other developers? If so, explain what type of contributions are welcome to your project, and what your requirements are for accepting them.
## Install and run {TOOL_NAME}
For others to contribute to your project, they need instructions to help them get started. For example, is there a script they should run or environment variables they must set? List the steps required to install and run your project locally, including any required dependencies. Provide a step-by-step description of how to set up and run the development environment.
Example:
## Credits
List any contributors and individuals, teams, or organizations who contributed to your development of this tool.
## License
Link to a file or page where you declare the license for your code. For more details, see [[wikitech:Help:Toolforge/Developing_successful_tools#Pick_a_license]].