All man pages i've seem seem suitable for tty. No diagrams, pics , math types. So it seems man pages currently still use text-formatting suitable for tty typed display devices. Since todays we have also display devices types with better resolution (called pixel) (*) surely it makes sense to have some sort of man page capable of containing info for both.

There is a pattern here. New display/input devices will always come along. In the context of helpsystems @ do we keep help systems along in their initial form ? Do we add carefully support for new display types ?

Let's ponder on that... Do we have TTYs ? No. We have displays of  /visual/granularity/pixel type that can ALSO mimic o TTY's  (of /visual/granularity/text  type) . BUT if you wear glasses or visual displays are not our preferred types then that means that even if we dont have TTYs we need TTY's compatible data outputs. And surely most sysadms of devuan use mostly TUI shells .

So even if the display tech (input tech seems little behind it seems :-) ) changes it seems there are ways of computing that dont die . Ways of computing suitable for diferrent ages , different computers users , a11y oriented  etc .

So framing the current state  : Manpages are currently alinged mostly  for a tty display type  and  text oriented processing type of computing workflows . One could say that that aligns better for programmers and sysadmins. (so no worries?) . But wouldnt help if you could see a nice table , diagram or datatype structure ?  Or wouldnt help IF the manpage  systems could have a certain display flexibility. Containing a data core easily presented in most display types (haptic,visual,sound) and data that can have preferable display types ? 

Helpsystems could have various traits having lightweigth ones and heavy ones .

Also likewise why not using interactive tools (an emacs mode? ) to create man pages more easily.

(email MIME @ ) .

(*)(pixel cons @) Trying to do animation on pixel level more creators come to realise that editing to pixel level is time-devouring .Personal but.. you need structure , types to allow reusability-composability. Not only you can be cutoff from others but even you can not even reuse your own work . The issue ofcourse is not the granularity of the display tech so much (that should be generic) but different ways of doing computing .

Don't know if it's of use but included in the x11-apps pkg is xman, which may be of help to 'point and click' users. Inputting xman gets a tiny window that must be enlarged to use. Inputting xman -notopbox in a terminal (or script in menu), opens the Help page with Options and Sections menus at the top left, and a list of default key bindings. Colors can be set: xman -notopbox -bg black -fg green, and Ctrl+q quits.

Very cool, thanks for posting that, learned something new today.

As noted by @chomwitt there is a proliferation in documentation systems. In actual practice, the situation that historically started with :man pages", has been successively aggravated in time by a chain of successive concerted attempts to make "a better help system", through 1, 2 or a few year spurts into new-system setups and tooling, and then simply dropping the ball upon the humongous task of modifying all existing documentation for the new-system approach.

Nowadays there also seems to be effort to break up (or down) "man pages" by collating them split off from their subjects into side packages, and many sorts of destructive actions, that when questioned get motivated by statements like that the man pages are too ugly, too hard to understand or to out-of-date etc.

In any case, in my view it remains essential that software gets documented in respect of how to use it (as well as ideally in terms of design principles, actual implementation choices and even sub system architecture).

there's a lack of really good and clear documentation to write man pages, i know there are videos out there, forum posts and articles about writing documents with roff and some even delve on the differences between roff dialects and implementations like groff, nroff, troff, etc... but they all have the same problem, they are written as narrations/articles which isn't the ideal form to ingest information dense topics, i find the best way to ingest and digest any topic with high information density is through the structured sections of wiki pages and ironically man pages as those are also structured by sections...

so, knowing that there are man pages that need to be written for this project it would be nice to have a wiki page and a manpage about writing manpages, and i know there will be some that will say "just write in asciidoc and convert to a manpage" and i'm not invalidating that but a manpage is not a mystical lost language, it is just roff, which is admittedly not great to write by hand but not impossible, so covering how to write a manpage by hand shouldn't really be a "no one will ever do that", that said for the task of writing the wiki page and the manpage that are to have the refference on how to write manpages both by hand and asciidoc it would make sense to write the source in asciidoc so it can be "easily" converted to both formats

for some repos i write manpages directly in roff and they come out okay cuz i cheat copying the manpages of other projects as template/base (usually the sxiv/nsxiv manpage) and editing it, but doing that has limits like when i want to add some usage or even code examples onto the manpage which i've had to format in less than ideal manners...

I present the wiki page as testing showcase of how i think a wiki could relate to various help systems used from Devuan Project.
I have transfered some ideas presented here there. Tell me if you dont like ideas trasnfered there.

In a few words a wiki (remote text-collaboration website) could be a  slow-paced user-admin workflow integrator incubator. That would position it (as a help system) in the opposite direction from a fast-paced-critical im or irc helpsystem-channel. In my test page at the top there a category tag. There a wiki user could see all user related efforts to formulate related workflows and express opinion on a user usefullness gradient and collaborate on a consensus building common wikipage.

So if you find the idea promising you could

• ask wiki admin onefang in the irc #devuan-wiki to create an account for you .

• create a personal wiki space @

• post on a  wikipage your worklow and

• link it to the same category [[!SharingFiles]].  @

All these are personal views-ideas. I am a user of the Devuan wiki.
For my general views : HelpSystemSemantics @

Some additional propositions  :

@chomwitt's proposition / welcome app / add a chatbot backend tied to an irc local client . It doesnt have to be LLM level. Even adventures of the 80s had interesting text parsers!. I remember LarryLaffer 's designer explaining in a video how he collected hundreds of possible questions from beta testers and aligned his game text parser to these questions!

@chomwitt's proposition / welcome app / offer offline copy of Devuan site , Devuan install guide and currently a variation of Debian begginers handbooks  (also see if it's @exercises can be downloaded)

@chomwitt's proposition / create 'man devuan' page.

@chris2be8 proposition / offer help to establish connection to internet offering specific and general advices .
(that could be tied to the @EDX-0's welcome app.)

@chomwitt's proposition / welcome app / offer connection to a irc devuan channel for new users

@chomwitt's proposition / installer / linux newcomers / history&basic usage in loading screens : Installer by default (or in less powerfull mode) could present unix-linux-debian-devuan history snippets intermixed with basic user knowledge. (unix mantras etc) .

Of course there are a lot of reasons a network connection could fail, but at least they would have some chance of fixing it.

Also speaking of user guides let me remind the FreeBSD Handbook @. But i dont think is contained in a FreeBSD installation.

and as it turns out i happpen to have a script for that leveraging fzf

https://github.com/eylles/mansearch

could probably write a manpage for it, put out a release tag and maybe look to package it for debian if there's any interest

$ sudo dpkg -i debian-beginners-handbook-en_13.3_all.deb 

$ dpkg -L debian-beginners-handbook-en 
/.
/usr
/usr/bin
/usr/bin/debian-beginners-handbook-en
/usr/share
/usr/share/applications
/usr/share/applications/debian-beginners-handbook-en.desktop
/usr/share/debian-beginners-handbook-en
/usr/share/debian-beginners-handbook-en/the_beginners_handbook.pdf
/usr/share/doc
/usr/share/doc/debian-beginners-handbook-en
/usr/share/doc/debian-beginners-handbook-en/README.Debian
/usr/share/doc/debian-beginners-handbook-en/changelog.gz
/usr/share/doc/debian-beginners-handbook-en/copyright
/usr/share/man
/usr/share/man/man1
/usr/share/man/man1/debian-beginners-handbook-en.1.gz
/usr/share/pixmaps
/usr/share/pixmaps/debian-beginners-handbook-en.png

It basically a pdf. It has a nice touch though. It installs a script command that open the pdf:

#!/bin/sh
xdg-open /usr/share/debian-beginners-handbook-en/the_beginners_handbook.pdf &
exit 0

Also as for the guide's history i found here the older versions @ and a 2017 version on the internet archives @

As for the authors  he has the nick arpinux .(website: @) and the guide is released under the WTFPL @

went to link @chomwitt provided:

https://debian-beginners-handbook.arpinux.org/index-en.html

and then further:

https://debian-beginners-handbook.arpinux.org/trixie-en/index.html

and downloaded the 17MB 267page pdf(warning: direct link to pdf download)

*ttps://debian-beginners-handbook.arpinux.org/trixie-en/download/the_beginners_handbook.pdf

fun read so far.

ymmv.