How could Xfce documentation be improved?

Jerry3904 · 2016-09-02 15:20:38

In the most recent Xfce4-dev mailing list digest (Xfce4-dev Digest, Vol 153, Issue 2), the devs have started asking some fundamental questions about improving the documentation. As someone who writes a lot of the documentation, I think this would be a great chance for this group to provide some thoughtful user-based reflections and suggestions for this important topic.

Here are 3 possible areas of general commentary that occur to me and that I mention merely as examples:

Documentation for whom, exactly? There are excellent man pages for advanced users (e.g., xfconf-query), but what about for average end users?
What documentation structure? Hierarchical structures do not always match well with how users approach solving issues.
What medium should the documentation use? Our set of videos, created by a knowledgeable and talented dev, receives high praise from our users.

I am persuaded that the questions are often harder than the answers. Let's see what we can offer the devs looking at this from the bottom up!

Jerry3904 · 2016-09-03 10:45:10

<I'm having trouble keeping up with the flood of suggestions...>

kafran · 2016-09-03 13:54:36

I'm the one who started the subject of XFCE having a better documentation on the mailing list. I'm not a developer, I'm the "average end user". And I start this topic based on the difficulties I faced when starting with XFCE. I found information everywhere else but XFCE documentation. Most of the information on the portal are out of date. Others there are only screen-shots. And I think the way things are organized difficult to find information. I think Xubuntu has a really good documentation. So has Archlinux. But I think XFCE should have a nice documentation too. Actually it should be the best so the others could "drink" from here.

Jerry3904 wrote:

Here are 3 possible areas of general commentary that occur to me and that I mention merely as examples:
Documentation for whom, exactly? There are excellent man pages for advanced users (e.g., xfconf-query), but what about for average end users?
I have no idea how to use xfconf-query and how it could be useful for me. So, this answer the question.
What documentation structure? Hierarchical structures do not always match well with how users approach solving issues.
Yep, I don't think someone reads a software documentation from begin to end these days. People are more familiarized to start using the software and reads the documentation in a more interactive way, where the software lacks information.
I like Mallard way which is topic oriented, but it's not collaborative, and easy to edit, and modify and maintain as a wiki. And lacks search tool, tags, etc.
I like the wiki way. Archlinux do a good job on maintaning their wiki well organized.
What medium should the documentation use? Our set of videos, created by a knowledgeable and talented dev, receives high praise from our users.
The medium is the internet. Videos, text, photos, they could all be used since well listed and organized in a way we can find when needed.

By the way, where are those praised videos? I have never seen.

Att.

Last edited by kafran (2016-09-03 13:58:28)

Jerry3904 · 2016-09-03 14:50:03

Thanks for the response. The videos for MX Linux are listed off the Home page, as you might expect, and deal with a lot more than the DE, of course. The series can be found here:

http://www.mepiscommunity.org/videos/mx14
http://www.mepiscommunity.org/mx15videos

We also cover this topic in the Users Manual, Sections 2.4.5 and 3, where we attempt to give an overview and use Xfce documentation itself as a drill-down resource. That Manual, which we review and upgrade every 3 months, also is fully integrated with the videos.

http://www.mepiscommunity.org/user_manu … /mxum.html

For my part, I hope the devs might consider creating (or reusing appropriate existing ones) a set of videos as an integral part of future. documentation.

ToZ · 2016-09-03 16:52:30

One of the challenges I think is keeping the documentation valid for all users. I'm not sure if any distros still ship 4.8, but 4.10 is still being packaged, 4.12, as well as some distros that package post-4.12 versions of some of the components. The documentation would need to document the functionality and identify where the differences exist between versions.

Also important would be a focus on configuration options for each component. A central place to find a listing of what I can configure, how to do it, and the end effect (and this would include any hidden and/or gtk-based options). Again, this would need to somehow differentiate between versions of the components because many times options are added, removed and/or changed.

I would imagine that regular end users would gravitate towards to the functionality type of documentation where the more advanced users would look at the configuration reference type of materials (which may be more hierarchical in nature).

The resource effort to accomplish this and keep it up to date would be huge.

Jerry3904 · 2016-09-03 17:16:05

Thanks for jumping in--you raise an absolutely critical question, for sure. The workload must be kept under control from the beginning. One thing might be to consider inviting Xfce distros to share the work--which would require some careful front-end planning but seems doable to me.

I would imagine that regular end users would gravitate towards to the functionality type of documentation where the more advanced users would look at the configuration reference type of materials (which may be more hierarchical in nature).

That's how I see it as well.

Last edited by Jerry3904 (2016-09-03 17:33:53)

alcornoqui · 2016-09-04 01:03:17

Read the Docs has great support for versioning "so you can build docs from tags and branches of your code in your repository."

Amusingly, I found this when I searched for Xfce there: Xfce: The Missing Manual

Jerry3904 · 2016-09-04 10:44:30

That is good looking output, for sure--thanks for the link. I wonder how printing works out...

Here's my own take on this. The choice of software will depend on many factors, one of the most important of which is: who is going to do the work. There are lots of good writers and editors using an Xfce distro, for instance, who have no interest whatsoever in going through GitHub using the command line. Any documentation project that wants to leverage that workforce will need to examine the medium carefully from the perspective of the writer rather than of the developer, to whom Read the Docs seems to be addressed.

Magnus · 2016-09-04 20:57:23

The problem with the documentation wiki is that you can't register an account, you have to send an e-mail to the devs through the mailing list to get an account. This is too much of a hassle, and I'm not touching user-unfriendly mailing lists with a ten foot pole.

Last edited by Magnus (2016-09-04 20:57:59)

Jerry3904 · 2016-09-04 21:52:40

Magnus wrote:

The problem with the documentation wiki is that you can't register an account, you have to send an e-mail to the devs through the mailing list to get an account. This is too much of a hassle, and I'm not touching user-unfriendly mailing lists with a ten foot pole.

I agree--and I even sent that email to the list, was told I would be contacted and exactly nothing ever happened!

Misko_2083 · 2016-09-05 21:13:02

Jerry3904 wrote:

Here's my own take on this. The choice of software will depend on many factors, one of the most important of which is: who is going to do the work. There are lots of good writers and editors using an Xfce distro, for instance, who have no interest whatsoever in going through GitHub using the command line. Any documentation project that wants to leverage that workforce will need to examine the medium carefully from the perspective of the writer rather than of the developer, to whom Read the Docs seems to be addressed.

I think that the way documentation is done in a fine way, at least for me. But from a new or user's perspective I imagine a "how to" approach would be more friendly. Maybe that is the missing part. Something like https://www.linuxliteos.com/manual/customize.html
Video's are cool but sometimes they take too much time. The users usualy just want to be able search on how to do or customize something.
Maybe a teacher's perspective is better than the writers. You give them them the intro on basic concepts: This is desktop, this is a panel, panel plugins. Then you show them how to do or customize things.

thb · 2016-09-07 12:19:52

Consider expanding the wiki license to allow commercial distribution.

Jerry3904 · 2016-09-07 12:47:06

thb wrote:

Consider expanding the wiki license to allow commercial distribution.

Don't see right away how that would help...can you say a bit more about what you are thinking?

Last edited by Jerry3904 (2016-09-07 12:47:26)

thb · 2016-09-07 14:15:50

Jerry3904 wrote:

thb wrote:
Consider expanding the wiki license to allow commercial distribution.
Don't see right away how that would help...can you say a bit more about what you are thinking?

Yes, thank you for asking.

Like at least 20,000 others, I use and like Xfce4 on Debian GNU/Linux. Most software a Debian user employs has documentation the user can optionally, conveniently install for offline use, usually under a package name like "xfce4-doc". Unfortunately, Debian has no package xfce4-doc.

It has occurred to me that a snapshot of your [Xfce Docs] wiki might make a pretty useful manual for offline use by Debian users.

However, though Debian is not a commercial project, it has commercial users. Therefore, by policy, Debian will not distribute software or documentation that encumbers commercial use or commercial redistribution.

If it is important to Xfce's developers that Xfce4's documentation never be used commercially, then so be it. A company that uses Xfce4 can try to use it undocumented, or can develop substitute documentation, or can use an alternative like GNOME, or can use Xfce4 strictly online. But maybe, like many open-source projects, Xfce does not really care one way or the other. Maybe the noncommercial license was just an arbitrary choice made sometime, a choice that can now be changed.

You might ask, "Why not just read the wiki online?" Answer: At a given moment, not all users are online. Plus, some users who use a stable version of the software over Debian's two-year release cycle might just prefer a stable version of the documentation. Not all users want the latest.

If the intent is to discourage or prevent someone like the Debian Project from packaging Xfce4 documentation, then of course you should not change the license. In that case, it's working.

You may remember this: [https://lists.debian.org/debian-devel-a … 00009.html]. Because of problems with GNOME at the time, Debian flirted with making Xfce4 Debian's default installation desktop. I suppose that GNOME fixed the problem, because Xfce4 is still a nondefault (though featured and well-supported) option for Debian; but I don't suppose that the lack of offline documentation Debian can use helps.

I would prefer that Debian make Xfce4 its default installation desktop. Your liberalizing the wiki license would not by itself accomplish that as far as I know, but it couldn't hurt.

It may be that Debian isn't your thing. Maybe you use Arch or BSD or OSX or Windows or who knows what? Someone uses Debian, though. Xfce4 is well regarded by Debian users and Debian Developers.

So, since you have asked how Xfce documentation could be improved, I though that I should mention the reason a commercially agnostic license might help Debian users like me.

Thanks for listening.

Jerry3904 · 2016-09-07 14:44:55

Thanks, those are interesting points.

(I should note that I am just a nosy/pushy user, and have nothing at all to do with Xfce development.)

Xfce Forum

Sub domains

#1 2016-09-02 15:20:38

How could Xfce documentation be improved?

#2 2016-09-03 10:45:10

Re: How could Xfce documentation be improved?

#3 2016-09-03 13:54:36

Re: How could Xfce documentation be improved?

#4 2016-09-03 14:50:03

Re: How could Xfce documentation be improved?

#5 2016-09-03 16:52:30

Re: How could Xfce documentation be improved?

#6 2016-09-03 17:16:05

Re: How could Xfce documentation be improved?

#7 2016-09-04 01:03:17

Re: How could Xfce documentation be improved?

#8 2016-09-04 10:44:30

Re: How could Xfce documentation be improved?

#9 2016-09-04 20:57:23

Re: How could Xfce documentation be improved?

#10 2016-09-04 21:52:40

Re: How could Xfce documentation be improved?

#11 2016-09-05 21:13:02

Re: How could Xfce documentation be improved?

#12 2016-09-07 12:19:52

Re: How could Xfce documentation be improved?

#13 2016-09-07 12:47:06

Re: How could Xfce documentation be improved?

#14 2016-09-07 14:15:50

Re: How could Xfce documentation be improved?

#15 2016-09-07 14:44:55

Re: How could Xfce documentation be improved?

Board footer