Call Us Today! 877.742.2583




Blog
Skip to end of metadata
Go to start of metadata

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.