<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-2" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
Yes, this looks good. <br>
I agree with Jan that we maybe can simplify a bit. Here are some
additional suggestions that you might want to consider:<br>
- Instead of having three panes, just link to the documentation. I
think this makes it easier to get the iptel.org menus and context.
People can decide themselves if they want to open a new tab, window or
whatever using shortcuts in their browsers<br>
- The search form may be simplified a bit, either by removing fields or
making a Advanced >> link that shows more options<br>
- I think version of ser and module, as well as type of entity are
useful. Whether we need input parameters and flags? I think they are
more for developers and (if necessary) could be put on the advanced
form. The name of the entity is a bit like free text search I feel?<br>
- The flag field could be a drop down field with the available flags,
or checkboxes for each flag. I don't think people know what the flags
are (except the developers)<br>
- Maybe name of entity and free text search could be merged into one?
I'm not sure if we want to search across anything else than the name of
function or param? I think it would be useful to search in name, for
example you get type in "radius" to get all functions, params, and RPC
calls with radius in the name<br>
- If the form is dynamic, do we need a Submit button at all?<br>
- If we only have the search form and the output table, it would be
nice to have a horizontal "search bar" instead of a vertical form. With
the dynamic update one can quickly add for example parameters to get an
overview etc<br>
- I think the parameter flag is relevant in the output table, and the
flags should probably be listed in textual form. Or maybe even better,
each flag represents a specific property, so there could be one column
per param flag that is ticked off if the flag is set? This way we
could quickly see if a function is allowed in onreply route, failure
route etc. <br>
The drawback is that the search app has to be updated if more flags are
added<br>
- I think the column name "Param Flag" is a bit confusing. I assume
this is the number of parameters that the function takes? So it is not
a flag, the flags identify in which parts of ser.cfg the various
functions can be used.<br>
- I think we can start with a web 2.0 app and then see if it makes
sense to create something else or maybe just save static outputs that
people can view<br>
- I don't think we currently have any marks (#ref) in the html output
of the module docs. But I assume the stylesheet can be adapted. Jan, is
this possible?<br>
- I don't think the app will be able to know if the documentation is
missing. Only when following the link, the user will be brought to
either just to the module doc or, with #refs, to the right location in
module docs, and the user will discover that something is missing. <br>
So, I think we need a "Report missing or insufficient
documentation"-link for each element in the table. Maybe that can be
done by creating a form out of the table, a checkbox at the beginning
of each row, a comment field at the bottom, and a "Submit missing or
insuffient documentation report" button at the bottom<br>
- And finally, I disagree with Jan on the drupal integration. Maybe we
will want to include searchable html docs as part of an install
package, on another website, or we may (heavens no) switch system. I
think we will be able to get the headers, menus etc the same way we
have made the module docs (by embedding code as content on a drupal
page). Integration is the root of all evil and the more independent we
can make this, the better, IMHO<br>
<br>
g-)<br>
<br>
<br>
Jan Janak wrote:
<blockquote cite="mid4609120D.4070007@iptel.org" type="cite">
<pre wrap="">Hello,
The page looks impressive, I also find it quite complex. I think what we
need is much more simple system which will allow to do us roughly the
following:
1) Lookup a function/parameter/select/rpc by name (and optionaly ser
version you are interested in).
2) Generate alhpabetical lists of function. parameters, selects, rpcs
for a given version.
3) Generate lists of functions, parameters, and selects grouped by
modules.
4) Provide a PHP function which will take a function/parameter/select
name and SER version and will return a link to the documentation
page. Even better provide a drupal filter that will insert such
links automatically in drupal pages.
The whole system should be probably written in PHP because we will need
to integrate it with drupal. Some sort of drupal integration (filters,
taxonomy) would be very useful too, because this would buy us great deal
of automatition.
In general, take a look at drupal, <a class="moz-txt-link-freetext" href="http://www.drupal.org">http://www.drupal.org</a> and try to see
if there is any chance of integrating it with the system.
Jan.
Marcin Pazdro wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Hi all,
I'm going to improve the documentation search page (or rather to
create new search engine).
Here:
<a class="moz-txt-link-freetext" href="http://www.iptel.org/ser_documentation_dynamic_search_page_functional_specification">http://www.iptel.org/ser_documentation_dynamic_search_page_functional_specification</a>
I have placed a functional specification that describes main
guidelines of new search page.
I would like to get some feedback from you. Please let me know if you
have some comments, tips or questions.
pazdro :)
_______________________________________________
Serdev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Serdev@lists.iptel.org">Serdev@lists.iptel.org</a>
<a class="moz-txt-link-freetext" href="http://lists.iptel.org/mailman/listinfo/serdev">http://lists.iptel.org/mailman/listinfo/serdev</a>
</pre>
</blockquote>
<pre wrap=""><!---->
_______________________________________________
Serdev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Serdev@lists.iptel.org">Serdev@lists.iptel.org</a>
<a class="moz-txt-link-freetext" href="http://lists.iptel.org/mailman/listinfo/serdev">http://lists.iptel.org/mailman/listinfo/serdev</a>
</pre>
</blockquote>
</body>
</html>