Updating three highly visible FreeSWITCH docs.

signalwire · Jan 8, 2024 · 2023ac9 · 2023ac9
1 parent e7fb0eb
commit 2023ac9
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 82 deletions.
diff --git a/...ned/Documentation-Guidelines_13173162.mdx → ...CH-Explained/Documentation-Guidelines.mdx b/...ned/Documentation-Guidelines_13173162.mdx → ...CH-Explained/Documentation-Guidelines.mdx
@@ -1,77 +1,38 @@
 
 # Documentation Guidelines 
 
-
-
 ## About
 
-First of all, thanks for wanting to share your knowledge. The wiki is growing each day and these guidelines will help us to get that knowledge documented in a structured way. You can add anything that will help users to install, configure and use FreeSWITCH™. **Ads to third-party software are currently forbidden**; we might create a page for ads in the future. We do request that you follow some guidelines when creating content.
-
-Click here to expand Table of Contents
-
-* 1 [Goals and why this page exists](#goals-and-why-this-page-exists)
-* 2 [Wiki Markup](#-freeswitch--documentation-guidelines-)
-* 3 [Page Content](#page-content)
-
-#### Goals and why this page exists
-
-There are multiple goals with the wiki based documentation effort. First we want to be able to provide quality documentation that is easy to navigate through on the web. Secondly we also want to be able to create a PDF manual that contains all the documentation within it. This PDF file would be suitable for printing and putting into a binder. Lastly we want a professional touch to the documentation. Many projects, especially open source ones, have limited documentation or highly unusable documentation. We want to set an example in the open source community with easy-to-read and understand documentation. As a community we can create documentation that is of the highest quality.
-
-##### Keep It Professional
-
-When adding documentation please keep comments professional. Things that are not acceptable include:
-
-* Jokes, especially at the expense of other software projects.
-* Profanity.
-* Slang (colloquialisms can be difficult to understand and translate).
+First of all, thanks for wanting to share your knowledge. The wiki is growing each day and these guidelines will help us to get that knowledge documented in a structured way. 
 
-#### Wiki Markup
+Contributors can add anything that will help users to install, configure and use FreeSWITCH™. We do request that you follow some guidelines when creating content.
 
-* Check out the brief [Wiki\_tutorial](https://wiki.freeswitch.org/wiki/Wiki%5Ftutorial "Wiki tutorial"). It contains helpful information and links to get you started.
+:::caution
 
-Also, as of March 23, 2012, David Knell assisted with getting GeSHi syntax highlighting working. Here are some quick examples:
+**Ads to third-party software are currently forbidden**.
 
-Without syntax highlighting
+:::
 
-The following wiki markup...  
-&lt;pre>  
-&lt;include>  
- &lt;param>value&lt;/param>  
- &lt;stuff foo="bar">etc.&lt;/stuff>  
-&lt;/include>  
-&lt;pre>
 
-Yields this output...
+## Goals and why this page exists
 
-```text
-<include>
-  <param>value</param>
-  <stuff foo="bar">etc.</stuff>
-</include>
-```
+There are multiple goals with the wiki based documentation effort.
 
-With syntax highlighting
+1. We want to be able to provide quality documentation that is easy to navigate through on the web. 
+2. We also want to be able to create a PDF manual that contains all the documentation within it. This PDF file would be suitable for printing and putting into a binder. 
+3. We want to set an example in the open source community with easy-to-read and understand documentation. Many projects, especially open source ones, have limited documentation or highly unusable documentation.  As a community we can create documentation that is of the highest quality.
 
-This markup...  
-&lt;source lang="xml">  
-&lt;include>  
- &lt;param>value&lt;/param>  
- &lt;stuff foo="bar">etc.&lt;/stuff>  
-&lt;/include>  
-&lt;/source>
+## Guidelines
 
-Yields this output...
+### Keep It Professional
 
-```xml
-<include>
-  <param>value</param>
-  <stuff foo="bar">etc.</stuff>
-</include>
-```
+When adding documentation please keep comments professional. Things that are not acceptable include:
 
-Languages values include: c, perl, python, lua, and many more.
+* Jokes, especially at the expense of other software projects.
+* Profanity.
+* Slang (colloquialisms can be difficult to understand and translate).
 
-Titles
+### Titles
 
 When selecting a title it is important to select something relevant to the subject you are writing about. It is also important for searching and automated PDF documentation efforts that the titles follow a few basic rules.
 
@@ -83,22 +44,20 @@ When selecting a title it is important to select something relevant to the subje
 * Do not prefix anything with FreeSWITCH™ unless its meaning would be unclear otherwise. Everything on this wiki is about FreeSWITCH™
 * Use the singular of example not examples since more people will search for the singular and not the plural
 
-#### Page Content
+### Page Content
 
 Do not create a page which only reads 'see this other page'. If you see a page that does that, change whatever links to it to point to the correct place. This is not just for wiki readability, but also for the PDF where these pages look even worse than on a web page.
 
 FreeSWITCH™ is a trademark of OSTAG. Please be kind in helping OSTAG maintain its trademark status by ensuring the ™ symbol appears wherever FreeSWITCH™ is used in wiki editing by using the code &trade;.
 
-Avoid creating hundreds of small pages
+### Avoid creating hundreds of small pages
 
 Sometimes a small page is required, however when you are describing a single entity, such as mod\_dptools, which contains a bunch of small functions, it would be better to create one page that covers that, and link each object to the section using the # operator. Searching will work for these sub elements as well.
 
-Examples
+### Examples
 
-Examples should be in the format of "Language Example Name" e.g. "JavaScript Example answeringmachine.js"
+Examples should be in the format of "Language Example Name." For example: "JavaScript Example answeringmachine.js"
 
-Try to avoid FAQs
+### Try to avoid FAQs
 
 Most of the time a FAQ is not required for something. FAQs are helpful in some circumstances, however when writing documentation a FAQ can be less helpful than a proper explanation of the technology and addressing the potential questions by explaining the information without a Q/A session typed into a page. If the technology is properly explained there should not be any frequently asked questions, if there are, then the documentation needs to be revised :)
-
-
diff --git a/docs/FreeSWITCH-Explained/Introduction/index.mdx b/docs/FreeSWITCH-Explained/Introduction/index.mdx
@@ -1,12 +1,11 @@
 
 # Introduction
 
-### 0\. About
-
+### About
 
 In this Introduction we provide a brief overview of FreeSWITCH in laymen's terms. We will then introduce all the key concepts in FreeSWITCH, and guide you on how to navigate the documentation. By following this introduction, you should be able to setup a basic deployment of FreeSWITCH in no time. Should you decide to dig deeper, and get familiar with more advanced features, we provide the links where you can find that too. At the end we will also provide a walk-through of the [default configuration](../Configuration/Default-Configuration_6587388.mdx#mod_vp8), so that you can get a hands-on tutorial, and most commonly used features.  
 
-### 1\. What is FreeSWITCH?
+### What is FreeSWITCH?
 
 FreeSWITCH is a Software Defined Telecom Stack enabling the digital transformation from proprietary telecom switches to a versatile software implementation that runs on any commodity hardware. From a Raspberry PI to a multi-core server, FreeSWITCH can unlock the telecommunications potential of any device. Combined with our hosted cloud platform, SignalWire, FreeSWITCH can interconnect with the outside world and scale to any size. (Visit <https://signalwire.com> for more info)
 
@@ -20,15 +19,15 @@ Some common capacities, that FreeSWITCH is used for, include
 * [Softphone](Glossary_13173966.mdx#softphone)
 
 
-This list is by no means comprehensive, FreeSWITCH is extremely flexible, and can be used in any way you can imagine.
+This list is by no means comprehensive. FreeSWITCH is extremely flexible, and can be used in any way you can imagine.
 
 The [default configuration](../Configuration/Default-Configuration_6587388.mdx#mod_vp8) showcases a full-featured [PBX](Glossary_13173966.mdx#pbx) with many applications. 
 
-### 2\. Where can I run FreeSWITCH?
+### Where can I run FreeSWITCH?
 
 At it's core, FreeSWITCH is a library which can be [embedded](../Client-and-Developer-Interfaces/Embedding-FreeSWITCH/index.mdx#php) in your application on any device. However, more commonly, it is built to run as a [background process](https://en.wikipedia.org/wiki/Daemon%5F%28computing%29) (daemon in UNIX or Linux systems, service on Windows platforms). When you run FreeSWITCH as a daemon, you can use the [CLI ](../Client-and-Developer-Interfaces/1048948.mdx#or)to interact with FreeSWITCH.
 
-FreeSWITCH can run on many Platforms, including Linux, Mac OS X, BSD, Solaris and even Windows.
+FreeSWITCH can run on many Platforms, including Linux, Mac OS X, BSD, Solaris, and even Windows.
 
 If you don't want to operate your own server, the corporate sponsor of FreeSWITCH, [SignalWire](https://signalwire.com), provides cloud-hosted FreeSWITCH services from dedicated FreeSWITCH servers to auto-scaling cloud-hosted services.
 
@@ -40,7 +39,7 @@ Hardware requirements depend on how you will use FreeSWITCH. FreeSWITCH can run
 
 For more information about hardware requirements see [Release Notes](../Release-Notes/index.mdx#-freeswitch--release-notes-) and [Performance Testing and Configurations](../Configuration/Performance-Testing-and-Configurations/index.mdx). 
 
-### 3\. Architecture
+### Architecture
 
 When designing FreeSWITCH the goal was to have the following properties:
 
@@ -59,7 +58,7 @@ When you install FreeSWITCH with the [default configuration](../Configuration/De
 
 The [modules](../Modules/index.mdx#about) are grouped by the type of functionality they provide. We will now explore the types of modules, and what functionality is provided by each.
 
-#### 3.1 Module Types
+#### Module Types
 
 | Type                                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                       |
 | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

diff --git a/docs/FreeSWITCH-Explained/index.mdx b/docs/FreeSWITCH-Explained/index.mdx
@@ -12,7 +12,7 @@ tags:
 
 Welcome to FreeSWITCH™, the future of telephony.
 
-Newcomers should start with the [Introduction](./Introduction/index.mdx#api) page in the table of contents and follow the child pages for further information. 
+Newcomers should start with the [Introduction](./Introduction/index.mdx) page in the table of contents and follow the child pages for further information. 
 
 The documentation is not perfect, and we rely on your help to suggest improvements from a fresh perspective.
 
@@ -31,13 +31,21 @@ FreeSWITCH™ is an open source carrier-grade telephony platform implemented as
 
 Our documentation parallels the ongoing development by the FreeSWITCH™ core development team in concert with contributions from the open source user community. With your help, the docs will always track the latest version of code available from the git repository.
 
-The wiki provides usage prototypes and examples for the channel variables, dialplan applications, and API commands that can be accessed via E.S.L. (the Event Socket Layer) with scripts written in Lua, Perl, and other languages. Pages tagged with the label "[examples](/tags/examples)" provide reference information to configure and experiment with FreeSWITCH.Be sure to click on the labels to find pages that related to that topic.
+The documentation provides usage prototypes and examples for the channel variables, dialplan applications, and API commands that can be accessed via E.S.L. (the Event Socket Layer) with scripts written in Lua, Perl, and other languages. 
+
+{/* 
+
+NOTE: The tagging system needs to be rebuilt using Docusaurus tags instead of Confluence Labels. See https://github.com/signalwire/freeswitch-docs/issues/79 for more information.
+
+Pages tagged with the label "[examples](/tags/examples)" provide reference information to configure and experiment with FreeSWITCH. Be sure to click on the labels to find pages that related to that topic.
+
+*/}
 
 Reference documentation of core API functions can be found on [FreeSWITCH Tech Reference](http://docs.freeswitch.org/).
 
 ### Docs Team
 
-Many of these pages are contributed by the FreeSWITCH™ community over the years, some might be out of date and would benefit from your improvement. Ask for editor access to Confluence to join the party! Details can be found on the [Contributing Documentation](Community/Contributing-Documentation/index.mdx#about) page.
+Many of these pages are contributed by the FreeSWITCH™ community over the years. Some pages might be out of date and would benefit from your improvement. To get involved, visit the [Contributing Documentation](Community/Contributing-Documentation/index.mdx#about) page.
 
 
 ## Books
@@ -56,12 +64,4 @@ FreeSWITCH is an open source community project. If you find incorrect or outdate
 
 If you have questions about reading, writing, or reporting issues with the documentation, please join the [Community Slack](https://signalwire.community/).
 
-### Featured Pages
-
- - [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)
-
-