The Functionality of the Documentation System

Is it feasible to modify the functionality of the new documentation system, in particular its search features?

There are a few points on which the new documentation system’s search functionality is a little awkward, I feel, and I’d like to propose some changes–but I don’t know whether it’s particularly feasible to alter the system.

That depends, what did you have in mind?

The main thing that I have in mind is filtering for the searches: right now, the search is entirely indiscriminate–if I search for, say, “DirectButton”, I’ll get the manual page for it, the API page, and a variety of pages that just happen to mention it, whether API or manual.

In that specific case the results aren’t too bad–the class and manual pages are near the top. But I’ve had cases, as I recall, in which finding the intended page involved combing through a fair few result-items.

Thus it might be useful to be able to filter searches–to search only in the API, or only in the manual, and only in page-titles, or even only in class-names.

Another potentially-useful addition might be further cross-linking between the API and manual. While there is some of this, I feel that there could perhaps be more.

In the API itself, I note that while it includes the functions available from a given class, it doesn’t seem to include any variables, enums, etc. that said class might hold. Of course, the manual does document some of these–but I don’t think that it does so exhaustively. As such variables, enums, etc. can be quite useful, even important, I’d very much like to have them apparent in the documentation.

And finally, it seems that the new API doesn’t include sub-classes in its hierarchy listings, only parent-classes. I recall times in which it was handy to be able to simply click through to sub-classes from the hierarchy provided by the old API, and so I think that it might be a useful addition here, too.

1 Like

Please file all these suggestions as separate issues on the issue tracker here:

“More cross-linking” is a good suggestion but a little vague and therefore hard to make actionable; are there specific examples you can name?

Fair enough! I’ll hopefully do that soon. :slight_smile: (Perhaps tomorrow.)

Hmm… I’m not sure, offhand; it’s something that I recall noticing. I think that one thing might have been a desire for more links from mentions of classes in the manual to the pages for those classes in the API. After all, since it’s all one documentation system now, why not allow frequent and easy movement from manual to API?

To some degree I’m perhaps bringing over experience from TVTropes, where near-everything is wiki-worded, and thus it’s easy to traverse through the information.

(I’ll hopefully give this more thought when I come to write up a proper issue for this in the tracker.)