Jump to content

Documentation/Tool doc template

From mediawiki.org

This is a basic template for documenting Wikimedia tools. It includes sections for each of the essential components of tool documentation in a single page or document.

The template 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} ==

This tool helps you do {_______}.  It does {_______} so that you can {_______}.

Project status: actively maintained | not maintained | ... other

__TOC__

=== Basic functionality ===

{TOOL_NAME} is intended for use by {target user}. It is meant to help {target user} do {main objectives}.

''Give a basic description of what the tool does and how it does it, but leave technical details for later.''

{TOOL_NAME} uses {_______} to do {_______}.  It takes {_______} from {_______} and uses it to {_______}. For more details about the technical implementation, see [[#Developer_documentation|the developer documentation]].

=== What {TOOL_NAME} does not do ===

'' 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 even if they have all the prerequisites?''

This tool cannot do {_______}. It does not have {_______}.

== Prerequisites ==

Before using this tool, you should be familiar with:
* {the basics of {_______}, how to use {_______}}
* {software, programming languages}

You should have:
* {software, operating system requirements}
* {hardware requirements, RAM}
* {permissions, access, account requirements}

== How to use {TOOL_NAME} ==

'' 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.''

=== {Do a thing} ===

# Step 1
## Sub-step a
## Sub-step b
## Sub-step c
# Step 2
# Step 3

''When a user has completed all the steps you list, they should have successfully done the thing you named in the section header.''

=== {Do another thing} ===

# Step 1
# Step 2
## Sub-step a
## Sub-step b
## Sub-step c
# Step 3

''When a user has completed all the steps you list, they should have successfully done the thing you named in the section header.''

== Troubleshooting ==

{One thing that can go wrong}
* How to resolve it

{Another thing that can go wrong}
* How to resolve it

== How to get help and report issues ==

* Report issues at {your issue tracker or process}.
* Ask questions or get help at {where to contact you}. You can expect a response in {time period}.

== Developer documentation ==

=== Technical implementation ===

''Provide a brief technical overview of how you implemented the tool's main functionality.''

This tool uses {some library, API, platform, other technology} to do {some technical operation}. It depends on {some library, API, platform, other technology} because it uses {some technology} for {some technical operation}.

=== Code structure ===

''A high-level description of the code architecture, focusing on what a developer would need to understand if they were trying to get oriented to the repository so they can contribute code or debug an issue.''

The {_______} module does {_______}.  The {_______} directory contains {_______}.

=== Local development ===

==== Set up ====

How to set up development environment:
# {Write the step here.}
## {Substep 1}
## {Substep 2}

==== Install ====

How to install:
# {Write the step here.}
## {Substep 1}
## {Substep 2}

{Optional: Include a code sample or screenshot that helps your users complete this step}

==== Configure ====

How to configure:
# {Substep 1}
# {Substep 2}

==== Build and test ====

How to build and run locally:
# {Write the step here.}
## {Substep 1}
## {Substep 2}

How to run tests:
# {Write the step here.}
## {Substep 1}
## {Substep 2}

==== Debugging ====

* {specific error message or log/console output}
** How to resolve the error, or what the log output means

* {specific error message or log/console output}
** How to resolve the error, or what the log output means

== How to contribute ==

The {TOOL_NAME} maintainers welcome contributions! (OR)...are not able to accept contributions at this time.
* {Type of contribution you want}
* {Another type of contribution you want}

=== Contribution process ===

Before contributing, read the {Code of Conduct} that outlines community guidelines and expectations.  We follow {style guide / coding conventions}.

# {Write the step here.}
## {Substep 1}
## {Substep 2}

# {Write the step here.}
## {Substep 1}
## {Substep 2}

== 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.

Markdown

[edit]
## {TOOL_NAME}

This tool helps you do {_______}. It does {_____} so that you
can {_______}.

Project status: {actively maintained, or....other}

### Basic functionality

{TOOL_NAME} is intended for use by {target user}. It is meant to help
{target user} do {main objectives}.

*Give a basic description of what the tool does and how it does it, but
leave technical details for later.*

{TOOL_NAME} uses {_______} to do {_______}. It takes {_______} from
{_______} and uses it to {_______}. For more details about the
technical implementation, see [the developer
documentation](#Developer_documentation).

### What {TOOL_NAME} does not do

*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 even if they have all the prerequisites?*

This tool cannot do {_______}. It does not have
{_______}.

## Prerequisites

Before using this tool, you should be familiar with:

-   {the basics of {_______}, how to use {_______}}
-   {software, programming languages}

You should have:

-   {software, operating system requirements}
-   {hardware requirements, RAM}
-   {permissions, access, account requirements}

## How to use {TOOL_NAME}

*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.*

### {Do a thing}

1.  Step 1
    1.  Sub-step a
    2.  Sub-step b
    3.  Sub-step c
2.  Step 2
3.  Step 3

*When a user has completed all the steps you list, they should have
successfully done the thing you named in the section header.*

### {Do another thing}

1.  Step 1
2.  Step 2
    1.  Sub-step a
    2.  Sub-step b
    3.  Sub-step c
3.  Step 3

*When a user has completed all the steps you list, they should have
successfully done the thing you named in the section header.*

## Troubleshooting

{One thing that can go wrong}

-   How to resolve it

{Another thing that can go wrong}

-   How to resolve it

## How to get help and report issues

-   Report issues at {your issue tracker or process}.
-   Ask questions or get help at {where to contact you}. You can expect
    a response in {time period}.

## Developer documentation

### Technical implementation

*Provide a brief technical overview of how you implemented the tool's
main functionality.*

This tool uses {some library, API, platform, other technology} to do
{some technical operation}. It depends on {some library, API, platform,
other technology} because it uses {some technology} for {some technical
operation}.

### Code structure

The {_______} module does {_______}. The {_______} directory contains
{_______}.

*A high-level description of the code architecture, focusing on what a
developer would need to understand if they were trying to get oriented
to the repository so they can contribute code or debug an issue.*

### Local development

#### Set up

How to set up development environment:

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

#### Install

How to install:

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

{Optional: Include a code sample or screenshot that helps your users
complete this step}

#### Configure

How to configure:

1.  {Substep 1}
2.  {Substep 2}

#### Build and test

How to build and run locally:

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

How to run tests:

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

#### Debugging

-   {specific error message or log/console output}
    -   How to resolve the error, or what the log output means

<!--code example -->

-   {specific error message or log/console output}
    -   How to resolve the error, or what the log output means

## How to contribute

The {TOOL_NAME} maintainers welcome contributions! (OR)...are not able
to accept contributions at this time.

-   {Type of contribution you want}
-   {Another type of contribution you want}

### Contribution process

Before contributing, read the {Code of Conduct} that outlines community
guidelines and expectations. We follow {style guide / coding
conventions}.

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

<!-- code example -->

1.  {Write the step here.}
    1.  {Substep 1}
    2.  {Substep 2}

## 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.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Documentation/Tool_doc_template&oldid=6483523"