New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Show inline field description in documentation explorer #169
Comments
@OlegIlyenko - I think what you have in mind is great. We can also do an expand/collapse style of inlined descriptions, but showing the first paragraph (or a sentence or two really) if it gets too long sounds like a great start. Something to keep in mind is that @leebyron and I were talking about something similar to this (in context of |
Could we have an button aside the field name,and follow with the first line of the description,after we click the eg:
and after click the
|
@joelgriffith what you have is so awesome - thanks for taking your time to help out. I personally like the second one, except that it still doesn't resolve the original concern 100% and the user has to click the arrow(s) individually to show the descriptions. Maybe |
Yeah, would an |
I think showing the first line of text might get a bit redundant - we can start with |
@joelgriffith Thanks a lot for looking into it and sharing your ideas! Generally I think the idea to expand field is pretty interesting. Maybe we can add "Expand All"/"Collapse All" toggle in the "Fields" header? Now that I think about it, if we already allow to expand fields' description, then maybe we can change the UX a bit:
I these docs represent this ides pretty closely (try to click on the method descriptions): http://www.scala-lang.org/api/current/scala/collection/immutable/HashMap.html WDYT? |
I'm on board for that, could be considered a breaking change from a user perspective, but it fairly easy enough to implement |
@joelgriffith are you still considering sending a PR for this? |
Definitely, was mostly waiting to hear back from maintainers at this point before putting in the work. I have some code that I could dust off on this. |
At this point we have a few competing ideas:
And a few combinations/nuances overlaid, such as "expand/collapse all", pagination, and so on. In the abstract, I think the way to move forward is to try building a few of them and take them for a test drive. Personally and concretely however, I think we can rule out hover as a UI anti-pattern. I'm also not a huge fan of expand-on-click, given that the original motivation was to give an overview at a glance without requiring a heavier-weight interaction, and additionally because it would be splitting the doc explorer paradigm into two models (one where clicking navigates to a new view, and another where it modifies an existing view inline; I think it's better to keep things pure and stick to a single model). So my vote would be to build an initial cut that shows inline. If the descriptions wind up being too long in practice, only then would I look at adding a way to collapse/expand them. And finally, the very last thing I'd do is look at pagination. |
That looks like a good start to me, @joelgriffith. Once you get the ellipsis overflow working, how about sending a PR for us to poke around in? (Also, will solicit feedback from person with actual design-talent; I'm just a taste-challenged engineer.) |
Update mocha to the latest version 🚀
I think this is done. Right @acao? |
yes it is, thank you @bdougie ! |
At the moment fields look like this:
In contrast, enum values, for instance, which have an inline documentation for all of the values:
I find it very helpful to see the documentation for all of the fields or enum values in one view, especially when I'm trying to learn new API.
So my suggestion is display descriptions inline for fields as well:
This raises a concern: I guess field descriptions tend to have much more information in them than an enum values. I can also imagine putting an example code snippet in the description. Maybe in this case we can truncate the description and show only a first paragraph or something along these lines?
I would be really interested to know your opinion on this :)
The text was updated successfully, but these errors were encountered: