Situation

The current documentation contains a short introduction to the ICS format, an API description, some "advanced usage" section, and others.

However, in its current state, the documentation IMHO has some problems:

• Mixup of Different Documentation Types
  The documentation doesn't distinguish between API, Tutorial, Quick Starts etc. Yes, somehow they are all there, but they mixed up and aren't distinguished properly.
• Lack of Examples
  As ICS itself can be complex, it is not always clear how to use all the classes, functions, and their parameters. There are some brief examples in the Quickstart section, but as soon as it gets more complicated, the developer is lost.
• Not aware of the Needs of a Developer
  The documentation has one specific target group: developers. As such, the documentation needs to address the needs for this group. For example, a developer needs to know how to install the library, how to use them, and maybe how to expand it.

I don't want to sound too negative, but these issues above makes it hard to find answers to questions developers may have when using this library. Some questions could be:

• What is the difference between datetime.datetime and arrow.arrow.Arrow? When should I use the former, when the latter? What are the pros and cons?
• How can I create recurring events?
• How can I create events that have specific properties?

When I've discovered this library, I was exactly finding answers to above questions. IMHO, the documentation should provide answers and help developers.

Proposed Solution

First of all: An API summary is not a user documentation! An API is a reference of classes, functions, etc. usually automatically created.
It can be useful when you need to know which signature a function has, which datatypes are required etc. But an API is bad at describing the "big picture". 😉

So when I write "documentation", I mean user documentation.

So how could we make better user documentation? First of all, we need to put ourselves in the shoes of an ordinary developer. Think of a developer who discovers this library for the first time, wants to use them, but has limited time. What would he need?

One way to do that is to think of "actions": read an existing ICS file, create a new calender, create new events, create specific events, write a ICS file, etc. Plus we need to distinguish between referential text (APIs, ICS overview) and procedural text (using the library).

From this idea, I derived my table of content:

1. Quickstart
    This contains a very brief overview how you can use the library.
     It could also add a list of features.

2. Overview of the ICS format
    Describe the format, give some background information,
    what are the benefits, what are the problems? Should the
    developer be aware of some incompatibilities? Can the
    format be extended?
   Could also be located at the end of the documentation.

3. Installing ics
    Probably a very short chapter, but not all developers know
    how to install a library in Python.
    Usually with pip, but maybe there are specific actions needed
    for other OSs?

4. Using ics
    4.1 Reading an ICS file
    4.2 Accessing Events in a ICS file
    4.3 Creating a new ICS calendar
    4.4 Creating Events
    4.5 Creating Recurring Events
    4.6 Creating Special Events
    4.7 Adding Custom Properties to Events
    4.8 [....]

5. Troubleshooting ics
    If something goes wrong, this could be the chapter to find
    solutions. 

6. Contribute to ics

7. API

8. Changelog
    Document the changes from version to version. Usually, this
    can be done (semi)automatically.

Of course, there are other ways to structure the documentation. It's one idea.

But as you can see, it distinguishes between procedural texts (starts with a verb like "Using", "Creating" etc.) and referential texts (have nouns like "API").

Benefits

• Your documentation is an advertisement of your work.
• Helps developers to know all of the feature and the potential of this library.
• Keeps developers happy (know how to use it, less time spent on finding correct code).
• Clarifies goals and requirements.
• Reduce time spent on finding accurate answers.
• Serves also as a "knowledge base" when people open issues which are already answered and documented.

See also

Good examples of documentations:

• https://python-semver.readthedocs.io/
• https://docs.pytest.org/