Improving user experience in the OCaml Documentation Tutorials

[Ndipbanyan]

Issue description

When you navigate to /docs and click on Read the tutorials button, you will be directed https://ocaml.org/manual/index . On this page I noticed that the OCaml Manual is divided into parts and each part has some chapters in it. When you click on any of the chapters, a page with the content of that chapter is displayed along side a hamburger(Which in my opinion isn't a great thing to have on a desktop sized screen. ) in which clicking(the hamburger) displays the other content of the Part which the current chapter belongs to. Refer to the screenshot below to view what I am referring to:

Having the content of the other sections of the current part at that position and having to click the hamburger to display or close them can be better positioned or improved.

Suggestions

In my opinion, having this content displayed on the right hand side of the page and styling it to a fixed position (so that no matter how far down the page a user goes, the user will still have that menu displayed to navigate easily.) will give a better user experience. Please refer to https://docs.docker.com/get-started/ to see a view of my suggestion

However, this observation affects almost the whole OCaml Manual and I am not sure if it is something anyone can easily fix within the contribution period.

PS:

This is suppose to be a part of what I intended to include in my Outreachy final application as part of what I would love to contribute to improve the ocaml.org website project if/when I am selected to be an intern, but I am putting it out here considering that the fact that I feel it isn't something I can easily achieve during the contribution period doesn't mean someone else can't. But then if the mentors are thinking in the same line as myself(that it is an issue worth fixing and and can't easily be fixed during the contribution period, then I have easily found one of the things to improve in the Ocaml.org website when/if I get selected as an intern.

I would love to have a feedback on this. Thanks

[yashi-hub]

if this issue gets approved, I would love to implement it within the contribution period :)). as I'm done with creating a PR for a good-first-issue and improving some docs already, I'm willing to work on other issues and this interests me a lot:). @patricoferris what do you feel about this?

[yashi-hub]

hey @patricoferris please can you have a look at this? I believe that this can be counted as an issue of medium-complexity as referred in https://github.com/ocaml/ocaml.org/issues/1245. if approved , I would love to start working on it as soon as possible :))

[patricoferris]

Thanks for raising the issue @Ndipbanyan and starting the conversation. This sounds like a good idea.

Changes to the OCaml Docs can be prototyped here directly on the HTML, but ultimately the contribution needs to be upstreamed to the compiler repository https://github.com/ocaml/ocaml/tree/trunk/manual. We might want to take a page and do a rough prototype (just change the HTML/CSS) to see what this looks like, then we can get the opinion of the ocaml/ocaml maintainers to see if they would like to upstream it. See this similar issue as to how it has worked before https://github.com/ocaml/ocaml.org/issues/1279.

[Ndipbanyan]

Thanks for raising the issue @Ndipbanyan and starting the conversation. This sounds like a good idea.

Changes to the OCaml Docs can be prototyped here directly on the HTML, but ultimately the contribution needs to be upstreamed to the compiler repository https://github.com/ocaml/ocaml/tree/trunk/manual. We might want to take a page and do a rough prototype (just change the HTML/CSS) to see what this looks like, then we can get the opinion of the ocaml/ocaml maintainers to see if they would like to upstream it. See this similar issue as to how it has worked before #1279.

@yashi-hub You might want to try what was suggested here I suppose. Best of Luck

[gs0510]

@yashi-hub Were you able to make any progress? Do you have any questions or need any help? :)

[yashi-hub]

hey @gs0510 , I'm working on it. I'm trying to fit things described on the issue. It is taking a bit of time because it requires many changes. I'll get back to you if I need some help :))

[yashi-hub]

Hey, @patricoferris @gs0510, I have worked a lot on this issue, I have almost achieved what was described here. but I'm just facing an issue

https://user-images.githubusercontent.com/69522036/114382388-ef35f080-9ba9-11eb-9e4a-94f5253141ea.mp4

I have uploaded the video, in this, the right-hand side content is fixed as described by @Ndipbanyan above. but the introduction to OCaml (just this one line of text) is also getting fixed automatically because, in the code, both these things are enclosed in the same div. and as a result, when we scroll down, the right side remains intact (as desired ) but the introduction to OCaml is getting overlapped with the other text when we scroll down. can I get some help on how to resolve this :))

[gs0510]

@yashi-hub You can move Introduction to OCaml to another div which doesn't have to be sticky.

[yashi-hub]

https://user-images.githubusercontent.com/69522036/114720358-95722980-9d55-11eb-8d80-df8c7b9763d5.mp4

hey @gs0510 @patricoferris , I created a new div for the introduction to ocaml and now all the text that is scrolled goes behind that div and no overlapping occurs. ( I've tried to apply the layout in the same way shown in -https://itrish.com/ ) we cannot move the introduction to ocaml part upwards on scrolling because it is directly attached to the button that is responsible for opening and closing the right div (correct me if I am wrong, or anything related to that can be changed). if we allow the introduction to ocaml part to also move upwards on scrolling, then the users who want to close the right div while reading will have to go all the way up, and then close it.

but if we go with this design which I just now attached, it has a lot of extra spacing in between. to make it not look weird, can I increase the font size of introduction to ocaml ?

also, this is what I understood with the issue described above, if I'm missing some more elements to edit, please let me know. thanks :))

[yashi-hub]

hey @gs0510 @patricoferris looking forward to your reply so that I can progress further on this issue.

[gs0510]

Can you also add a video of closing the right div @yashi-hub? Is the awkward whitespace we see right now still persist when you close the right div?

[yashi-hub]

hey @gs0510 @patricoferris. I have made some more changes, now the website works completely as desired both on the phone screen as well as desktop screen and the white spacing is also removed. please have a look before I create a PR

https://user-images.githubusercontent.com/69522036/115199683-15f7a800-a111-11eb-8232-2835e1c885a4.mp4

if you feel the need for some more changes, I will be more than happy to implement them. thanks:))

[gs0510]

This looks great @yashi-hub! You should open a PR with your changes :)

[yashi-hub]

thanks @gs0510 , i just wanted to ask that in the manual section there are few more pages with the same issue of right div .

1. https://ocaml.org/releases/4.12/htmlman/language.html
2. https://ocaml.org/releases/4.12/htmlman/comp.html
3. https://ocaml.org/releases/4.12/htmlman/core.html

so should I make the same changes in all these files before creating a PR?

[gs0510]

Yes, that'd be great @yashi-hub ! Thanks!

[yashi-hub]

hey @gs0510 @patricoferris, just had a quick problem before opening the PR the work which I have done till now on these pages is according to the code that I extracted from https://ocaml.org/releases/4.12/htmlman/coreexamples.html using ctrl+U and that code (or the live website rn) doesn't show chapter number in the right div. for eg:

but before creating a PR I need to add the code changes to the ocaml.org repository. and in that, the same file i.e. coreexamples.html when run locally shows chapter numbers also (P.S.- this is the same version i.e. 4.12 )

if I go by the ocaml.org code, then there is not enough space on the right-hand side to fit the complete text properly with all the chapter numbers and chapter names. but if I go by the code of the live site, everything seems to work fine as I have shown in the video above. can you please tell me how should I proceed further with the PR?

[patricoferris]

Are you sure you are using the latest master branch commit from upstream? You might need to do a git pull upstream master to get the latest changes.

The chapter numbers are not there afaict https://github.com/ocaml/ocaml.org/blob/master/site/releases/4.12/htmlman/coreexamples.html#L10

[yashi-hub]

Are you sure you are using the latest master branch commit from upstream? You might need to do a git pull upstream master to get the latest changes.

The chapter numbers are not there afaict https://github.com/ocaml/ocaml.org/blob/master/site/releases/4.12/htmlman/coreexamples.html#L10

oh yes, I did not get the latest changes. sorry about that. I'll just create a PR now for all the pages. thanks for the help :))

[yashi-hub]

Hey @gs0510 @patricoferris I've submitted a PR for this issue, changing all the files. If some more changes are required to the site, I'll be happy to implement it. Kindly review the PR. Thanks :))