Documentation/Library Documentation Template

Libraries Documentation

Who should use this template?

This template is suitable for writing any form of library documentation and shouldn't be used for anything else.

Template

Below is the provided template for this particular genre and is to be duly followed when creating documentation.

Title

The name of the library should be written boldly at the top. For this template, a title is not needed.

Getting help

Having trouble? We’d like to help!

• Check the FAQ (Link to be added). It has answers to lots of common questions.
• Looking for specific information? Check the Library Index (Link to be added) or the detailed table of contents above.
• Found a bug? Report bugs on our GitHub repository here (Link to be added).

Getting started

Here's what you need to know to start using Library X!

• What is Library X?
• How do you install Library X?
• Concepts in Library X
• Writing your first X scripts

Contributing to X

Learn more about how you can make X a better library

• X review process
• Coding style and guidelines
• Help forums
  • Stack overflow
  • IRC
  • Slack
  • Gitter

Getting help

The audience needs to know where they can visit when they are stuck or have issues. You should provide a link to:

• FAQs
• Module index
• Bug reporting

The FAQ as the name implies is a page that contains a list of basic questions that the audience is most likely to have with the respective answers to those questions. A separate document should be created for the FAQ, and you can use this template (Link to be added) as a starting point and guide.

The module index is a list of all methods and APIs that this library provides. It should be added towards the end of this page, and a link to it should be provided.

Libraries are bound to have bugs. The way bugs are reported vary from library to library, so you should state how bugs should be reported to your library here and provide all useful links.

For example:

Having trouble? We’d like to help!

• Check out the FAQ. It has answers to lots of common questions.
• Looking for specific information? Check the Library Index or the detailed table of contents above.
• Found a bug? Report bugs on our GitHub repository.

Getting started

This section should explain what the library does in-depth, put the audience through how to install the library, and also introduce them to its basic syntax.

What is library X

This part should answer the following questions:

• What does this library do?
• What problem is it trying to solve?
• Why was it created and who was it created for?
• Who created it and when was it created?

Installation/setup guide

The audience needs to know how this library can be appropriately installed or set up. You should walk them through:

• The prerequisite software needed for this library to be installed or set up
• The step-by-step process to install or set up this library
• What version of this library should be installed for specific cases
• How to verify that the installation was successful

Some installation guides might be quite lengthy. For such guides, you should consider creating a quick start guide and share a link here instead.

Writing your first X

In this section, you'll be introducing the audience to the basic syntax of the library. You will walk the audience through a very small but simplistic code snippet and explain what it does. The idea is to get them to see what the usage of this library looks like and how simple using it can be.

Here is an example taken from the scrapy documentation explaining its basic usage.

Scrapy example

import scrapy


class QuotesSpider(scrapy.Spider):
    name = "quotes"

    def start_requests(self):
        urls = [
            'http://quotes.toscrape.com/page/1/',
            'http://quotes.toscrape.com/page/2/',
        ]
        for url in urls:
            yield scrapy.Request(url=url, callback=self.parse)

    def parse(self, response):
        page = response.url.split("/")[-2]
        filename = 'quotes-%s.html' % page
        with open(filename, 'wb') as f:
            f.write(response.body)
        self.log('Saved file %s' % filename)

Concepts in X

Different libraries are used for different things, and each has their own terminologies and concepts. Here is a good place to explain such concepts in as much detail as is sufficient to get the audience started.

Let's assume this is a state management library for a frontend framework. An example of concepts worth explaining would be state, mutations, getters, actions, etc.

Tutorials and how-tos

This is where you explain the usage of this library in-depth. There are two options you could adopt based on the nature of the library:

• Have the tutorials on this page
• Create a separate document for each tutorial and provide links here

The first should be used if this is a minimalistic library and there aren't many tutorials (i.e. about 3 short tutorials).

If there are more than 3 tutorials, you should consider moving each to a separate document and providing links to them here. You can use the tutorials & walkthroughs template or the quick start guide template as a guide for creating these documents.

However, this particular document must contain a guide on how to set up a project with the library.

Setting a project

Here you should discuss what is required to get a project started with this library and how to set it up.

• What are the requirements?
• What's the recommended folder structure?
• How can this library be used or imported? (Over CDN or needs to be installed?)
• If both of the above, give examples of each.

Module index

The module index is a list of all modules, methods, and APIs this library provides and a brief explanation of what they do.

This can be added as a list here if there aren't too many of them, or a separate document containing these lists can be created with a link to it provided here.

Contributing to X

This is a guide explaining how people can contribute to this library. Contributions do not have to be code contributions; they can come in any form, but this guide should cover all the forms in which contributions are welcomed! Additionally, you should consider including the following:

• Explain the development workflow (i.e. how code moves from commit to PRs to being merged).
• Explain the code review process.
• Explain the coding style/guidelines.
• Encourage people to help as much as they can in talk forums and places like Stack Overflow. You could provide links to these forums.

You should have a look at Numpys contributor guide.

Stewardship

Here, you would share useful information about the following:

• Who maintains this page
• What projects are included
• How to contact the author and maintainers of this project (only share public information here, like Zulip or IRC)
• Links to discussion pages or threads