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

[Bogdan-Andrei Iancu]

Hi Brett,

indeed, the SGML looks very nice when comes to generating docs in other 
formats, but in our case it is not practical - we use it only for HTML 
docs which will be anyhow replaced by wiki.

So, I think having the master copy in wiki and generate the READMEs (or 
others) from wiki should serve the purpose much better.

With the versioning, you have a point there - there are 2 approaches there:
    1) MYSQL like - they keep all docs already sorted by version
    2) php like - there is single entry per function with all 
adnotations related to versions.

But I prefer the mysql one as the function behaviour and params may 
change - I think it will be more clear to keep them sorted per version. 
when generating the pages for a new version, we can place links to the 
comments for the previous versions - like backward links :). This is 
will be the easiest to maintain as there will be no doc duplicity.

Regarding the comments - this first version for the comment tool does 
not support threading or notification, but I can search for some more 
advanced comment tool for pmwiki.

Regards,
Bogdan



Brett Nemeroff wrote:
> Speaking as a user here...
>
> I don't reference the READMEs in the modules themselves very often. 
> However, I hit the website documentation several times a day.
>
> Although I like the whole concept of SGML in SVN producing such 
> pretty,repeatable formating in your  documentation, I don't know that 
> it's really necessary. And that kind of structure is preventing users 
> from adding comments that may otherwise keep you from having to answer 
> the same question over and over. :)
>
> I personally wouldn't mind just seeing the docs in wiki format 100%. 
> With proper CSS, it'd look identical, right? However, there is the 
> issue of module version I'm not sure how to deal with. For example, I 
> may have a question about USAGE of a module in 1.4 version and a 
> specific example may get posted to the wiki. But it may only be 
> applicable in 1.4. On the other hand, an example may be applicable to 
> newer versions as well (like if an exported function changes the 
> number of accepted parameters).
>
> As for each function on it's own page. That may solve some of this 
> problem.. But at the same time, I'd probably be good to be able to 
> generate the whole thing as well (the whole module). I don't really 
> care as long as it's nicely hyperlinked.
>
> Of course, on the commenting, there should be the ability to be 
> notified of updates. I'm not sure if this deserves a full blown 
> own forum.. ultimately that would be good.. so lets say under the 
> dialog module, the set_dlg_profile() function, someone may post a 
> thread like "How to set a profile from an avp value" and there may be 
> a whole discussion. I may choose to get updates to just that 
> discussion (on just that module).
>
> In the typical wiki sense as well, there should be a way to watch 
> pages for edits and to be notified. 
>
> That's my $0.04. I don't know how you have time to deal with any of 
> this anyway. :) Thanks for all your hard work.
>
> -Brett
>
>
> On Tue, Mar 3, 2009 at 8:11 AM, Bogdan-Andrei Iancu 
> <bogdan at voice-system.ro <mailto:bogdan at voice-system.ro>> wrote:
>
>     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
>     Users at lists.opensips.org <mailto:Users at lists.opensips.org>
>     http://lists.opensips.org/cgi-bin/mailman/listinfo/users
>
>