Revised documentation for OBK ?

[ghost]

Currently, alot of the documentation for OBK are severely outdated, for example, there are still build instructions for Solus, which is practically dead, or setup instructions for Unity DE.
Meanwhile, distros like NixOS/Fedora Silverblue and technologies like Wayland are on the rise, documentation for which are almost entirely absent from the wiki pages.

As the release of OBK3 is approaching, It would be best if the docs got a proper revision. I am personally willing to help out in this regard, and am opening this discussion in hopes of further conversation regarding this.

[mominul]

Yes, yes, we need docs the most!
We'll have to document new features of OBK 3 alongside documenting DE integration tutorials.

If you do #367 then you can easily grab the screenshots and document their processes. We'll need to cover:

• Gnome DE using ibus
• KDE using fcitx5
• Deepin using fcitx
• Mate (ibus or fcitx5?)
• Cinnamon (bus or fcitx5?)
• ZorinOS (ibus or fcitx5?)

New features that need to be documented:

• ASCII typing
• Creating new layouts using obk-layout-editor and installing it using the TopBar লেয়াউট ইডিটর / বিল্ডার #345
• An overview of all the features that OBK offers.

Thanks in advance! ❤️

[ghost]

Mate, Cinnamon and ZorinOS all use DEs which are modified/forked from GNOME.
So I believe they should be defaulting to ibus.

Should the docs be in Bangla, English, or both ?

I can boot up VMs and document the process, but as I won't be daily-driving them, some edgecases and other quirks might not get documented, I invite regular users for feedback.

[mominul]

Mate, Cinnamon and ZorinOS all use DEs which are modified/forked from GNOME.
So I believe they should be defaulting to ibus.

Yeah, I think too. But ZorinOS Lite uses Xfce

Should the docs be in Bangla, English, or both ?

Bangla would be enough.

I can boot up VMs and document the process, but as I won't be daily-driving them, some edgecases and other quirks might not get documented, I invite regular users for feedback.

Yeah surely.

[ghost]

Leaving this comment to assess the current state of the docs.

[ghost]

From the Cinnamon wiki page :
১. আপনার Shell এর কনফিগার ফাইল এ এই তিন লাইন যোগ করে নিতে হবে। অধিকাংশ মানুষ Bash / ZSH ব্যাবহার করে তাদের জন্য যথাক্রমে ~/.bashrc অথবা ~/.zshrc ফাইল এ এই লাইন গুলো যোগ করে নিতে হবে। আমাদের পক্ষে সব shell এর config দেওয়া সম্ভব নয়। যারা অন্য গুলো ব্যাবহার করেন তারা নিজ দায়িত্বে এই কমান্ড এর সমতুল্য কমান্ড বসিয়ে নিবেন।

https://man.archlinux.org/man/environment.d.5
https://devdoc.net/linux/man7.org-20170728/man5/environment.d.5.html
There is a shell-independent way of setting envvars on systemd distros. more robust and probably preferable to editing .bashrc or .zshrc

[ghost]

The Cinnamon and Mate docpages show distro-specific commands or workarounds which are redundant, or insert personal preferences
For example on the MATE DE page : Now go to the General tab and choose a Keyboard shortcut for changing your layout between English and OpenBangla Keyboard. You can see below that I've chosen it to be F12.

[ghost]

The readme on the "Code" page can be shortened and can be linked to the "Build" wiki pages for the Compilation instructions

[ghost]

So far, the requirement for docs seem to be

• Build instructions (Distro-specific)
• • Debian
• • Fedora etc
• Install instructions (Distro-specific)
• • Ibus
• • • Fedora
• • • Debian etc
• • Fcitx
• • • Fedora
• • • Debian etc
• DE-specific setup instructions (Distro-agnostic)

Thus, any ibus/fcitx-specific quirk of a distro that needs to be fixed should be in "Install instructions" section

[mominul]

* Install instructions (Distro-specific)

* * Ibus

* * * Fedora

* * * Debian etc

* * Fcitx

* * * Fedora

* * * Debian etc

Can you elaborate on what you mean by separating install instructions by IM engines? I think if we give the choice to the user about the selection of IM engines, novice users will be confused. So my thought on this issue is that we give the best 'happy path' installation procedure by DE, like for Gnome we'll suggest the user install the ibus engine of OBK and follow its integration steps.

[ghost]

Can you elaborate on what you mean by separating install instructions by IM engines?

Sorry it came off confusing, my intent was to have a section that lists the DEs which primarily favour ibus or fcitx (or both), and tell the user to choose the appropriate version based on that, but also document any quirks/advice that are specifically related to ibus/fcitx and not the DEs/OBK themselves, as in figuring out what IM the user is currently running etc. So basically what you have suggested plus some extras.

[ghost]

Should EoL versions/distros be supported ? (e.g. Ubuntu 16.04 or Solus)
I have questions about how WMs like Sway/hyprland etc are going to be handled.
For now I will be targetting Fedora and Debian as distros, then GNOME/KDE/Cinnamon as DEs for the docs.

[mominul]

Should EoL versions/distros be supported ? (e.g. Ubuntu 16.04 or Solus)

Nope, we'll skip EoL distributions.

[ghost]

It appears that Github won't let me fork the git repo for the wiki, nor clone the wiki when I fork the OBK repo.
How should I handle forking the wiki repo ?

[mominul]

You can fork the wiki by following some workarounds but no support for merging the changes. So this is not useful to us.

You can manually edit and commit the wiki changes by Github UI, but that is a bit tedious.

We can try a documentation generator like Mkdocs which seems to output nice docs and there is a simple one: mdBook. These can output static sites from ordinary markdown files, so we can host them in an ordinary git repository and have the fork-merge workflow.

[ghost]

I have had pretty decent experience with mdbook
Infact, the GTK4 book for Rust is written in it, and it works decently well (can even output to pdf and epub)

https://gtk-rs.org/gtk4-rs/stable/latest/book/
https://github.com/gtk-rs/gtk4-rs/tree/master/book

[mominul]

I have had pretty decent experience with mdbook

@larina3315 Great, let's start then! I have created a repository for the user manual, manual. I have added you as a collaborator in that repo.

[ghost]

Thank you, I will move the conversation to that repo and close the discussion.