Observations on FreeSWITCH Documentation

[rh000000]

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

[briankwest]

Could you attend our next FreeSWITCH meeting and lets go over it all, We accept pull requests and updates here as needed, maybe we can work together to improve the process as we just started down this path.

EDIT: https://mailchi.mp/freeswitch.org/office-hours