Skip to content
This repository has been archived by the owner on Dec 21, 2023. It is now read-only.

FAQ usability rewrite. #116

Closed
wants to merge 25 commits into from

Conversation

jamesbt365
Copy link
Member

@jamesbt365 jamesbt365 commented Aug 24, 2023

Begin the rewrite of the FAQ pages, open to suggestions.

I have no idea how to format this nicely or write proper docs (or English at all really) so a review on what I have written would be nice.

Incomplete as I'm opening this, so marking as draft until complete.

This will break the FAQ snippets in Discord, as well as any previous links sent in GitHub or elsewhere. I can try and make it as compatible as possible if that is desirable, but I don't know how to handle that at this time.

fix #42
fix #43
fix #109
fix #110

@jamesbt365 jamesbt365 added the enhancement New feature or request label Aug 24, 2023
@jamesbt365 jamesbt365 marked this pull request as draft August 24, 2023 12:21
@jamesbt365 jamesbt365 added documentation Improvements or additions to documentation wiki Improvements or additions to wiki labels Aug 24, 2023
@jamesbt365
Copy link
Member Author

jamesbt365 commented Aug 24, 2023

image
Its bulky currently, but I'm not sure on how to make it look better or thin it out and yes, I'm aware of a few missing newlines.

@jamesbt365
Copy link
Member Author

I have added back all the FAQ entries for Windows, some reworded and some mostly the way they were.

I feel like further changes are required to have the same "flow" on the other entries like how the first one is structured.

I can't write the titles as I want because longer titles mean it squishes the page content to the right more, which is undesirable here. If I remember I'll try and figure out a way to remedy this so I can use full length titles.

@jamesbt365
Copy link
Member Author

This pull request currently supersedes #89, will fix #110 and #109 and potentially OpenTabletDriver/opentabletdriver.github.io#116 when done.

Copy link
Contributor

@Sublimelime Sublimelime left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Several grammar fixes, addition of commas, and some elaboration.

OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Windows.cshtml Outdated Show resolved Hide resolved
@jamesbt365
Copy link
Member Author

I have gone ahead and pushed the start of the Linux FAQ rewrite, I'm not happy with it so far because I feel like grouping stuff together may result in making it harder to point people towards the right instructions, but the readability of this is much better.

I have left a placeholder instead of listing the message for missing udev rules as this is usually indicated by a hidraw error (the log message saying udev rules don't exist has been gone for a long time now OpenTabletDriver/OpenTabletDriver#2333) but the hidraw error also occurs when OTD tries to open other devices that may not be tablets, so it may not be the most reliable message to use.

@jamesbt365
Copy link
Member Author

jamesbt365 commented Oct 2, 2023

TODO (maybe):

  • Fix formatting on some segments (I believe this is done?)
  • Fix english
  • Make it not so cramped
  • Try and fix the contents list.
  • Add an extra part for udev misconfiguration, as OTD will occasionally show the hidraw message for non tablets resulting in the same problem.
  • Amend the service instructions
  • Include non-systemd distro instructions
  • List artist mode for reasons other than pressure (misbehaving cursor in wine, other XWayland applications and SDL applications on Wayland)
  • Cleanup other less important and or redundant instructions

The MacOS FAQ probably will not be handled in this pull request as we do not have an extensive FAQ for this platform at this current moment in time.

@jamesbt365
Copy link
Member Author

I pushed a change that will affect how the "contents" segment is shown, I have tested this explicitly in firefox testing as a pc and using responsive design mode to check how a mobile device will handle it. I want opinions on this change but it makes the wiki far less cramped.

old:
image
image

new:
image
image

fix formatting in other places.
@jamesbt365
Copy link
Member Author

I've gone ahead and pushed some stuff on artist mode, I'm not sure if we packaged the smoothing override yet so I've gone ahead and included it here.

@gonX
Copy link
Member

gonX commented Oct 2, 2023

I'm not sure if we packaged the smoothing override yet so I've gone ahead and included it here.

Smoothing override is not packaged yet, but I think it's planned. OpenTabletDriver/OpenTabletDriver#2895 tracks this.

@jamesbt365
Copy link
Member Author

jamesbt365 commented Oct 2, 2023

New push should fix OpenTabletDriver/opentabletdriver.github.io#116. I went down the route of explaining what convert_to_portable.bat does rather than directly the userdata folder because we have that script packaged with all Windows releases now.

I have also included basic non-systemd instructions. #42

I'm not very happy with the way that the ENOENT solution is placed, it
feels completely out of place and I just want to remove it entirely and
tell people to refer to their distros documentation on how to modify the
kernel.

The only place where the problem is typically present is on gentoo and
people using gentoo probably know how to enable and disable specific
parts of the kernel, so pointing them towards the documentation for
gentoo or just telling them to visit it is probably enough.
@jamesbt365
Copy link
Member Author

I'm not very happy with the way that the ENOENT solution is placed, it
feels completely out of place and I just want to remove it entirely and
tell people to refer to their distros documentation on how to modify the
kernel.

The only place where the problem is typically present is on gentoo and
people using gentoo probably know how to enable and disable specific
parts of the kernel, so pointing them towards the documentation for
gentoo or just telling them to visit it is probably enough.

@jamesbt365
Copy link
Member Author

jamesbt365 commented Oct 3, 2023

Other than formatting, SPAG (includes turning british english into american english) and some elaboration on using diagnostics to find missing udev rules (current method is has flaws) I think I am ready for review!

@jamesbt365 jamesbt365 marked this pull request as ready for review October 3, 2023 14:07
@jamesbt365
Copy link
Member Author

This pull should:
supersede #89
fix #42
fix #43
fix OpenTabletDriver/opentabletdriver.github.io#116
fix #109
fix #110

@jamesbt365
Copy link
Member Author

Note to self: include switching to debug mode to see the logs in console.

Copy link
Member

@gonX gonX left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM aside from my suggestions, current formatting and subject ordering isn't the greatest but it's a huge upgrade over what we have now

OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.cshtml Outdated Show resolved Hide resolved
The CSS styling for Markdown looks scuffed but that is a separate project
@gonX
Copy link
Member

gonX commented Oct 8, 2023

6eaa160 preview:
image

@gonX gonX requested a review from Sublimelime October 9, 2023 11:29
Copy link
Contributor

@Sublimelime Sublimelime left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gone over it again with various grammar fixes, comma and info adds, etc. Looks good otherwise.

OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md Outdated Show resolved Hide resolved
Improve Linux FAQ structuring
unsure on the macOS path at this time.
@gonX
Copy link
Member

gonX commented Oct 29, 2023

This doesn't entirely fix OpenTabletDriver/opentabletdriver.github.io#116 btw.

That issue requests talking about the userdata folder, and that folder is only vaguely referenced in this PR's current state.

But it does fix #117

@jamesbt365
Copy link
Member Author

If it isn't enough I'll just remove it from scope. I don't exactly have the drive to "finish" this any more than I currently have so it will remain out of scope unless anybody wants to submit a pull request to my fork to add it.

@jamesbt365
Copy link
Member Author

This should be in good enough state to be merged as is, but as it stands I am really losing the drive to push anything else into this at the current time, more along the lines of the whole project overall ;-;

@jamesbt365
Copy link
Member Author

done on migration to opentabletdriver.github.io

@jamesbt365 jamesbt365 closed this Nov 21, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Improvements or additions to documentation enhancement New feature or request wiki Improvements or additions to wiki
Projects
None yet
4 participants