[OpenSIPS-Users] [website] Documentation re-structuring

[Bogdan-Andrei Iancu]

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