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

[Brett Nemeroff]

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>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
> http://lists.opensips.org/cgi-bin/mailman/listinfo/users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.opensips.org/pipermail/users/attachments/20090303/0e03c056/attachment.htm