Hi, Following some previous discussion on the topic of the docs should be organized on the website in order to serve in the best way to the users, I would would like to get some feedback/opinions/suggestions from all of you in regards to this topic.
As per previous announcement, there are now some adds-on on the website (like login and comments) that will help a lot, but need to re-structure the docs in order to take advantage of these features. Current issues: ---------------- 1) Module documentation is HTML format and cannot be edited 2) The doc for a module is in a single chunk (all parameters, all functions, all MI, etc), so it is impossible to use comments in such a format. Solution: --------- First of all I suggest spliting the documentation for a module in multiple pages - one page per function or per parameter - this will allow to add at the bottom of the page a comments section. Secondly, it's about the content: 1) do we keep the content in a non-editable format and fully correlated with the SGML from SVN? in this case we rely only on comments to improve the docs (docs master copy is in SGML and the web site will be updated only) 2) we do copy the current SGML content in wiki format, so we can edit is also. Later we can update the README files from wiki (before releases). In this case the master copy is the wiki. Also there will be no need for SGML as we keep only the README (generated from wiki) - actually all the docs will be generated from wiki, as the wiki will become the master copy. Personally I'm in favour of option 2) as it is the most flexible (as edit+comments and also as sync between wiki and README) and also because it will simplify the doc management on the SVN part. Other opinions ? Thanks and regards, Bogdan _______________________________________________ Users mailing list [email protected] http://lists.opensips.org/cgi-bin/mailman/listinfo/users
