Add user documentation

[blinry]

Unless I'm mistaken, there's no documentation at all on how to use dunst on the homepage and in the readme. Do I need to start a server? Which parameters can I use? How to configure the font?

[tsipinakis]

Proper documentation is a long-running issue. The best (and only) sources available currently is the manpage and the example config

[blinry]

Both are actually rather helpful! :) But you have to know they exist first. I'd suggest adding a visible "Usage" section both to the homepage and the README, which mentions those two.

Thanks for your work on this tool!

[bebehei]

A few days ago, I've thought about the same things, too. And just a dedicated site, where you have the basics covered (dbus-monitor, restarting dunst, DBus/systemd autolaunch, rule filtering, pausing dunst, ...) this would be great. In the long term run, this wouldn't just make new users more happy, it would also shift the level in the bugtracker here as ppl already know how to work with dunst and can give detailed information right from the start.

And as an additon to the introduction section, I think an additonal "Advanced"[1] page would make also sense. On that "advanced"[1] page, you combine things together. These could be real life world example snippets, which are explained to the user and have a special effect. At the end of the day you should give the user the possibility to see what dunst is capable of. A good example for this page would be an elaborated explanation for the recently introduced fullscreen rule.

And still in addition, FAQs, which answer a special question.

I have to admit, I'm too lazy to start proper docs for newcomers. I currently lack the vision, how to start with this.

---

[1] Call it however you want.

[bebehei]

A new user showed up in the IRC. Here's a list of traps, the user had fallen into:

• Icons don't work.
  • (We have to elaborate the cludgy icon_path setting).
  • icon_position is set to off by default. WTF?
• Dunst startup.
  • dunst "test" was expected to show a notification
  • the automatic dbus startup wasn't used and the xinitrc was preferred.
• "How can I send notifications?" was asked.

I think it might be a good thing to consecutively improve the documentation also covering the traps, the users are falling in constantly.

[bebehei]

Hey guys, I want to move the installation section from the README.md into /docs/installation.rst. This renders the README almost empty.

I'd love to put into the readme a good set of screenshots. This readme will also be the landing page of the readthedocs project. Are you able to show me your unixporn and make some cool screenshots showing dunst's abilities?

In the meantime, there's already a test project for dunst on readthedocs. I'm pushing regularly on there, see: https://dunsttestproject.readthedocs.io/en/docs/

[bebehei]

@tsipinakis at https://github.com/dunst-project/dunst/issues/596#issuecomment-457909449:

A release is overdue

Yeah, let's do a new release. I've created a new 1.5 milestone to cover the overnext minor release. And I've put all unnecessary work from 1.4 into the new milestone.

I would love to finish the docs before release. I think this is a blocker. Good software consists of two parts: Writing good software and using it properly. I claim, my software is good :tm: :wink:, so the only point left that others can use the dunst properly, we should provide good docs and especially guide them through the installation.

[bebehei]

We desperately need a "available since" tool. This would make so many things easier for users who report things like #604.

[tsipinakis]

A better approach would be to stick to a more regular release schedule say 4-6 months rather than the "when we feel like it" schedule we're on now. Even if there's no notable changes just release a minor version to ship any changes made in a reasonable timeframe.

Other than that, just annotating the settings in the docs with the first available version would be a good solution.

---

Also: Looking at the work you've done in #597 are you planning on copying the currents contents of the manpage to rtd and keeping both going? How are we going to keep them in sync?

[quirinux]

We desperately need a "available since" tool. This would make so many things easier for users who report things like #604.

ya that'd be really helpful for new comers like me, anyways I believe a good start point for issues like mime would be having a rough description of what each setting on config file does and, like said earlier on this thread, having a "available since" would be handy too.

I myself would prefer github wiki tool rather than readthedocs, keeping the whole project in one place, but I have to say readthedocs is a better solution for that, indeed splitting docs per version if desired, this is another way to avoid "available since" situation.

Another idea: github wiki could be used for dev docs like dependencies, compilers, gotchas and so on and readthedocs for usage manual like.

Anyways just let me know if you guys need a hand with that such usage documentation, I'd be glad to help.

[TRSx80]

are you planning on copying the currents contents of the manpage to rtd and keeping both going? How are we going to keep them in sync?

I would suggest strongly some sort of tool that allows keeping the source in one place, and then deriving all the docs from that into different formats (man pages, website, wiki, etc.) as automagically as possible. I don't know of a specific tool, but it seems other projects are doing this, to one extent or another.

Also, make it easy for new people to contribute changes. Most won't of course, but some of us will. Right after install is when all the little "gotchas" are still fresh in our minds.

Anyway, nice project. :smile: Thanks for sharing and maintaining. :beers:

[fwsmit]

I just did a search on duckduckgo to see what place will be found first by users. Duckduckgo pointed me at an empty readthedocs page. This should probably be deleted.

[bebehei]

I've reviewed my readthedocs account and had only a dunsttestproject there. Of course, I deleted it.

According to https://readthedocs.org/projects/dunst/, its @quirinux.

@quirinux Would you be so kind and remove the rtd project? Alternatively, you can also fill it with sensible docs :wink:

[quirinux]

@bebehei apologies for the delay in response, I've seen this just now, anyways, it is vanished from readthedocs now

[bynect]

I think this can be closed. Dunst docs have come a long way 👍🏻

[fwsmit]

Yeah, haha