Hi all, I'm going to improve the documentation search page (or rather to create new search engine). Here: http://www.iptel.org/ser_documentation_dynamic_search_page_functional_specif... 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 :)
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, http://www.drupal.org and try to see if there is any chance of integrating it with the system.
Jan.
Marcin Pazdro wrote:
Hi all, I'm going to improve the documentation search page (or rather to create new search engine). Here: http://www.iptel.org/ser_documentation_dynamic_search_page_functional_specif...
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 Serdev@lists.iptel.org http://lists.iptel.org/mailman/listinfo/serdev
Yes, this looks good. I agree with Jan that we maybe can simplify a bit. Here are some additional suggestions that you might want to consider: - 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 - The search form may be simplified a bit, either by removing fields or making a Advanced >> link that shows more options - 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? - 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) - 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 - If the form is dynamic, do we need a Submit button at all? - 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 - 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. The drawback is that the search app has to be updated if more flags are added - 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. - 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 - 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? - 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. 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 - 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
g-)
Jan Janak wrote:
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:
- Lookup a function/parameter/select/rpc by name (and optionaly ser version you are interested in).
- Generate alhpabetical lists of function. parameters, selects, rpcs for a given version.
- Generate lists of functions, parameters, and selects grouped by modules.
- 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, http://www.drupal.org and try to see if there is any chance of integrating it with the system.
Jan.
Marcin Pazdro wrote:
Hi all, I'm going to improve the documentation search page (or rather to create new search engine). Here: http://www.iptel.org/ser_documentation_dynamic_search_page_functional_specif...
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 Serdev@lists.iptel.org http://lists.iptel.org/mailman/listinfo/serdev
Serdev mailing list Serdev@lists.iptel.org http://lists.iptel.org/mailman/listinfo/serdev
Greger V. Teigre wrote:
Yes, this looks good. I agree with Jan that we maybe can simplify a bit. Here are some additional suggestions that you might want to consider:
- 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
Yes, I agree. Simplicity is the key here.
- 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?
No, search by name and version you are insterested in would be sufficient.
- 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
What is web 2.0? Do you mean automatic updates through javascript? Do you think this is really necessary for something that simple?
- 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?
Yes, that's easy to do.
- 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. 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
- 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
Well, OK, then at least a php function which will return to the documentation for a particular function name and version would be nice.
Jan.
2007/3/27, Jan Janak jan@iptel.org:
Greger V. Teigre wrote:
Yes, this looks good. I agree with Jan that we maybe can simplify a bit. Here are some additional suggestions that you might want to consider:
- 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
Yes, I agree. Simplicity is the key here.
I agree too. Originally we wanted to make search-page as sexy as possible, so, documentation loaded on-the-fly into documentation frame was great idea, but if we go to simplicity... So there will be just search frames and the generated table with links
- 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?
No, search by name and version you are insterested in would be sufficient.
OK, no problem
- 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
What is web 2.0? Do you mean automatic updates through javascript? Do you think this is really necessary for something that simple?
So, as I said. I wanted to create a fully dynamic working search-page where searching documentation, sorting and loading documentation does not require page reloading. AJAX! This framework (combination of XML, javascrip and dhtml is supported only by modern browsers). Originally it was meant not to be so simple as you think, Jan.
- 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?
Yes, that's easy to do.
:)
- 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. 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
This is a good idea Greger, however... When a user clicks the link in order to load (missing) documentation I doubt that after he/she discovers that there is no information he/she is looking she /he will like to go back to report missing documentation. But, I may be wrong. Nevertheless, I am going to implement this as you proposed :)
- 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
I was playing with all these drupal, taxonomies, hierarchies, categories... whatever. Although it seems to be really powerful, I'm afraid that getting understand how this really works and how to create php applets that could be easily included to the durpal schema may take much longer than just to implement new search-page. So, I consent to Greger's suggestion
Well, OK, then at least a php function which will return to the documentation for a particular function name and version would be nice.
OK. But we can still make it "sexy" and easy. We can still use AJAX (Spry framework). for searching for functions etc.. we can for example get similar effect as here: http://labs.adobe.com/technologies/spry/samples/data_region/NonDestructiveFi... On-the-fly table searching and sorting would not be a problem as well. More over, we could get rid of PHP at all. It would be enough with html and XML file. That file should have following structure: <documentation> <!-- Table iptel --> <iptel> <module>tls</module> <version>ser 0.10.99-dev66-tls (i386/linux)</version> <name>@tls</name> <type>3</type> <params>0</params> <link>somelink</link> </iptel> <iptel> <module>tls</module> <version>ser 0.10.99-dev66-tls (i386/linux)</version> <name>@tls.version</name> <type>3</type> <params>0</params> <link>somelink</link> </iptel> ... ... </documentation> This file could be generated together with documentation (is that possible Jan?) or if not, I could create some semi-exe php script that will generate that XML document once a day. Avoiding performing PHP scripts, searching databases or generating scripts as the documentation are requested will save server resources. :) Moreover, adding pure HTML (with some JavaScript) would not be a problem Best regards,
-
Greger V. Teigre -
Jan Janak -
Marcin Pazdro