[website] Documentation re-structuring

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[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

_______________________________________________
Users mailing list
[hidden email]
http://lists.opensips.org/cgi-bin/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

Re: [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 <[hidden email]> 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
[hidden email]
http://lists.opensips.org/cgi-bin/mailman/listinfo/users


_______________________________________________
Users mailing list
[hidden email]
http://lists.opensips.org/cgi-bin/mailman/listinfo/users
Reply | Threaded
Open this post in threaded view
|

Re: [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
> <[hidden email] <mailto:[hidden email]>> 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
>     [hidden email] <mailto:[hidden email]>
>     http://lists.opensips.org/cgi-bin/mailman/listinfo/users
>
>


_______________________________________________
Users mailing list
[hidden email]
http://lists.opensips.org/cgi-bin/mailman/listinfo/users