Update Broken Links

Issue

Past efforts to migrate and reorganize FreeSWITCH™️ documentation have broken a number of links throughout the repository. For example:

 - [Contributing Documentation](/confluence/display/FREESWITCH/Contributing+Documentation)
 - [Developers](/confluence/display/FREESWITCH/Developers)
 - [FreeSWITCH PBX Example](/confluence/display/FREESWITCH/FreeSWITCH+PBX+Example)
 - [mod\_verto](/confluence/display/FREESWITCH/mod_verto

Solution

Broken links should be replaced.

Hello dear friends, does this document site have plans for i18n?

Remove Legacy Comments from Documentation Migration

A number of FreeSWITCH documentation articles contain outdated comments which were preserved by a migration process.

These comments should be reviewed and deleted once any relevant information has been moved into the article content.

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update signalwire/actions-template digest to da0500a

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

As has been discussed elsewhere, a data-oriented way to index variables would be helpful. Thoughts on a JSON schema like this? I was trying to think of a way that would add as few additional dependencies as possible while also providing a good experience for writing these files. While configuration languages like jsonnet are nice, it would require pulling in a golang dependency.

My idea is to write variables in a YAML file and then validate them with the JSON schema. I don't think the JSON schema works yet, but I was just looking for input on if I'm missing anything and whether this would be useful.

{
  "$id": "urn:freeswitch:variable",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "$defs": {
      "dataType": {
        "items": [
          "uuid",
          "dtmf_key",
          "boolean",
          "number",
          "positive_integer",
          "string",
          "tgml",
          "file_path",
          "execute_on",
          "regex"
        ],
        "type": "string"
      }
    },
    "dataTypes": {
      "description": "The type or types that can be assigned to this variable.",
      "items": {
        "$ref": "#/$defs/dataType"
      },
      "type": "array"
    },
    "deprecation": {
      "$comment": "Don't worry about digging to find this information now, it's just for new deprecations.",
      "description": "Provide upcoming deprecation information.",
      "properties": {
        "deprecated": {
          "default": false,
          "description": "Whether this variable has been deprecated.",
          "type": "boolean"
        },
        "deprecatedAsOfDate": {
          "$comment": "This can be autogenerated from the release date of the tag.",
          "description": "The date after which this variable is considered deprecated.",
          "type": "date"
        },
        "deprecatedAsOfVersion": {
          "$comment": "Use the git release tag.",
          "description": "The version tag that deprecates this variable.",
          "type": "version"
        }
      },
      "type": "object"
    },
    "description": {
      "description": "The description of this variable.",
      "type": "string"
    },
    "examples": {
      "description": "A list of examples for how this variable can be used.",
      "items": {
        "properties": {
          "description": {
            "type": "string"
          },
          "source_path": {
            "$comment": "Use this in lieu of a description string if you find that it's easier to reference a file for an example",
            "description": "The path to the example",
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "introduction": {
      "$comment": "Don't worry about about digging to find this information now, it's just for new variables.",
      "description": "When this variable was introduced.",
      "properties": {
        "introducedAsOfDate": {
          "$comment": "This can be autogenerated from the release date of the tag.",
          "description": "The date after which this variable was introduced.",
          "type": "date"
        },
        "introducedAsOfVersion": {
          "$comment": "Use the git release tag.",
          "description": "The version tag that introduced this variable.",
          "type": "version"
        }
      },
      "type": "object"
    },
    "isCoreVariable": {
      "$comment": "This can be autogenerated from the presence of at least one `src/*.c`, `src/*.cpp` or `src/include/*.h` in a file in the references key.",
      "description": "Whether this variable is referenced in the core.",
      "type": "boolean"
    },
    "name": {
      "description": "The name of the variable.",
      "type": "string"
    },
    "isReadOnly": {
      "$comment": "Set to null if it is dubious as to whether the variable is read only.",
      "default": false,
      "description": "Whether this variable can be assigned new values.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "references": {
      "description": "Where this variable gets defined in the code.",
      "items": {
        "$comment": "Links to the source can be autogenerated by combining the version tag with the path and line.",
        "properties": {
          "columnEnd": {
            "type": "integer"
          },
          "columnStart": {
            "type": "integer"
          },
          "line": {
            "type": "integer"
          },
          "path": {
            "$comment": "The path should look like: src/switch_channel.c",
            "description": "The path to the file in the repository",
            "type": "string"
          },
          "version": {
            "type": "version"
          }
        },
        "required": [
          "path",
          "line",
          "version"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "name"
  ],
  "title": "Variable",
  "type": "object"
}

Hi all,

A few years ago I did a very incomplete index of FreeSWITCH variables based on the older wiki documentation as well as tried to think about how to organize the documentation. I made some progress, but not a lot.

I come back to the documentation a lot and here are some thoughts I've had over the years using it:

Structured documentation metadata

One thing that would be really helpful is if documentation were in some kind of structured language. There are a lot of options for this, be it XML, JSON, or even reStructuredText, but there needs to be some way to programmatically get documentation across different dimensions. For example, I've always wanted to be able to list every application available. Each module creates one or more applications, so being able to have a list of all applications with a backlink to their module page would be so useful! If there were some kind of metadata standard, this would really help documentation efforts. Version metadata would also help keep the documentation more up-to-date or at least it will help people know how up-to-date the docs are.

Doc writer vs. doc reader

I think what makes it easier for the documentation writer and what makes it easier for the documentation reader are two different things. For example, as a doc writer, it (to me) is way easier to organize the documentation on a per-module basis. So for example, all mod_sofia's documentation would be in one file with the variables, events, configuration, etc.

But the problem is that this doesn't always help with discoverability for the person reading the documentation, because some FreeSWITCH concepts reach across multiple modules. This goes back to the documentation metadata I was describing. Being able to reference variables from a particular module would be helpful since it allows doc maintainers to update in a single place. Of course there is still manual effort in keeping things updated, but I think it at least makes the process easier.

FreeSWITCH Snippets

In the documentation there are a lot of example snippets. These are very useful, but some of them ought to be a part of a kind of snippets site (see django snippets as an example). There you can see how authors post snippets and list the language and the version of Django. I think this could potentially help to make the documentation more focused.

Some way to index the FreeSWITCH project for variables/events

Variable/event indexing is incomplete. I thought a lot about how this would be done. My first and only attempt was to regex scan the FreeSWITCH project. But this missed a lot and was pretty error prone (for example, not taking into consideration variables whose names were actually defined with the C preprocessor). My next step was going to be to figure out doing some sort of C/C++ preprocessor thing to collect all known variables/events in the project. Having a reference on what and where variables are defined was pretty helpful in creating the variable list. Obviously, the most helpful was that a majority of the variables were already defined in the old wiki project. A revival of the old wiki project's attempts at indexing all the variables might be in order.

Hope this gives you some ideas,
Ryan

can we remove the : colons from the folder names in docs/FreeSWITCH-Explained/Modules/mod-dptools so us poor Windows users can clone the repo to work locally?

First of all, congrats on the migration to Docusaurus! Contributed a lot to the old, Confluence-based docs, but this one looks (and behaves) way better.

As for this issue, a couple of observations about the links in the header and footer:

• Header > "GitHub" (and under Footer > More) link to the signalwire/freeswitch repo. This documentation repo is not hard to find, but a link to it would probably be helpful.

• Footer > Docs > "Tutorial" yields a 404

• Footer > More > "Blog" yields a 404

• Footer > Community - all links point to Docusaurus community pages, which surprised me at first, but now at least I know what platform the new docs are using.

You are probably aware of all these, but didn't see an issue or PR regarding them.

Confluence Labels Need Updating

The Label tagging system in use when the docs were hosted on Confluence does not work.

Actions needed

These labels should be converted to Docusaurus Tags or removed.

Tags in Docusaurus

Docusaurus tags are added as a simple Markdown list under the tags front matter item.

---

tags:
 - introduction
 - example
 - etc

---

Sample labels in use:

• call-control
• channel_variable
• dialplan
• interop
• certificate
• encryption
• security
• sofia
• high-availability
• sms
• operating-systems
• installation
• dtmf

Issue

There are multiple overlapping introductory resources in the FreeSWITCH®️ documentation. See:

• FreeSWITCH-Explained/Introduction/
  
• FreeSWITCH-Explained/Introduction/Introduction.mdx

Solution

These resources should be consolidated to streamline the documentation and reduce confusion.

Standardize Filenames, Slugs, and Page Titles

Pages in the FreeSWITCH™️ documentation have inconsistent filenames. For example:

• Verto-Communicator_9633841.mdx
• IVR_13173361.mdx

Standardize references to FreeSWITCH®

FreeSWITCH® should be referred to using the trademark symbol and with SWITCH in all caps.

Not:

• freeswitch
• FreeSwitch
• etc

Update High-Visibility Pages

Issue

Several of the highest-visibility pages of the FreeSWITCH™️ documentation have broken links, outdated information, and references to previous wiki systems. For instance:

• docs/FreeSWITCH-Explained/index.mdx
• docs/FreeSWITCH-Explained/Introduction/index.mdx
• docs/FreeSWITCH-Explained/Community/index.mdx

Solution

Updating these pages.

Issue

Static tables of contents from past documentation and wiki platforms should be removed.

Example

mod_dptools: session loglevel

Click here to expand Table of Contents

1 Usage
2 Examples
3 Comments
4 See Also