27 Mar
2007
27 Mar
'07
4:12 p.m.
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.