Blog

Blog

Docs Sprint 2017.01.13

Come join the FreeSWITCH Documentation Sprint on Friday the 13th of January, 2017 to copy (hopefully) the remaining pages from the old wiki over here to Confluence. Once the last wiki page is copied over, Ken Rice will happily take a sledgehammer to the old wiki server (smile)

If you are not already a member of the Docs Team, let John Boteler or Italo Rossi know before the sprint day so that we can add you to the Confluence-editors group and also the wiki page tracker spreadsheet.

Details on the Wiki Migration page.

Thanks!

Docs Team 20140617

Permissions Corrected

I discovered that we had 2 different permissions groups after the Crowd back-end database was merged with the JIRA user database. Unfortunately, the larger group was not assigned any permissions at all in Confluence which is why most of the docs team experienced trouble. I moved everybody into the confluence-editors group and assigned that group the proper permissions so you all should be able to add and edit pages as necessary. Sorry for the mixup.

Spreadsheet

Belaid Areski has created a Google Docs spreadsheet to track the status of each page on the old wiki and who is handling it. Because access must be restricted please contact Areski if you prefer to use a particular account to access the spreadsheet.

He revealed that many of the old wiki pages do not need to be moved over to Confluence, but that still leaves a huge number of pages yet to be processed. Since the docs-team group permissions are now corrected, please begin copying pages over from the old wiki and mark them in the spreadsheet.

Workflow

When you copy a page from the old wiki over to Confluence, mark it "Moved" and enter the new URL under "New URL". Confluence uses the page title as the URL so avoid special characters and keep it short and simple.

If you edit the page to meet the Confluence Guidelines, then mark it "Editing" and enter your name or handle in the "Editing by" field.

Once you have completed editing the page, mark it "Completed" in the spreadsheet and find another page to attack.

Thanks.

Docs Team 2014.05.06

A brief weekly conference call Tuesday as work continues apace with only 2 active contributors copying and editing the wiki information. If you have a knack for technical writing please join the team to speed up this process. Create an account if you don't already have one and contact the Docs Team on IRC channel #freeswitch to find a section that is not already being handled.

Mario G has posted extensive installation instructions for Mac distributions and has also made a start on the massive Interoperability documentation tree. John Boteler is working through the Modules documentation tree.

Accounts

User accounts on JIRA had been used to access other portions of freeswitch.org but are being merged into Crowd for access to Confluence, Stash, and others for single sign on.

Documentation team conference call on Tuesday 2014.04.22 William King, Brian WestKen Rice, John Boteler, Russell Treleaven, Mario G

Purpose of Confluence

Confluence should be an up-to-date document presenting best practices and functional descriptions of installing and maintaining FreeSWITCH. Make Confluence closer to a book narrative, remove programmatic stuff from outline.

Structure

MarioG recommends writing sections dealing with specific topics similar to the approach of writing textbooks that support teaching of classes. Confluence should explain on a very high level what FS can do and how flexible it is to solve your business problems.

wking sez: prerequisites, machine architecture such as x86, RaspberryPi, et al.; how to install from source, packages, Windows binary, etc. For example, a section dealing with paging should treat different available types, such as record and page, multicast paging, callgroup paging, et al.

Provide typical small office setups: failover ITSPs, NAT issues and answers, CLID

ALSO warn people off setups that will lead them into trouble

doxygen

Doxygen automatically maps structures, variables, and functions, but it has not been maintained to current source code. It is not well-suited to the narrative documentation style intended for Confluence as it is intended as a reference and auditing tool for developers. http://docs.freeswitch.org only once removed from the source code and is a better choice for providing definitions of variables, functions, and API commands, although it shows FS version 1.0.6 so might be outdated.

Version Control

anthm wants the documentation to match the currently available software. A "stable" release only means that it is no longer being touched by developers, not that it is free of bugs, so there is nothing magical about it. Keeping only one documentation knowledge base that matches current code base parallels the idea that Jira tickets will only be considered if tested against the latest code base. This makes documentation easier because it evolves with the software and there's only one knowledge base to update.