I like your idea and created "Audience" tags for issues. The names are not so good but explicit. Hopefully we get to a point were we can define common vocabulary for those. In the meantime those labels should help figure what level of experience is the audience expected to have.

I think there should also be categories for "end user" (desktop), "ISP" (sysadmin), etc. that do not reflect a specific experience but a specific context.

I have mixed feelings about these labels. To me, trying to pigeonhole Devuan users/contributors into various categories is another layer of obfuscation because the definitions are very much moving targets.

I get your point @golinux . Still, I think it's nice to have a way to figure out what skill level is required to understand what part of the documentation, and keep an eye on balancing the contents so that everyone can get something out of it.

What do you propose instead to do this?

The more I think about this the more I'm coming to the conclusion that labels like these will tend to disempower users. Why not let the user explore on their own and let that experience dictate which docs they decide will be useful to them. The upside to labels is that it will make git pages very colorful (though a little busy and ADDish). ;)

@golinux the labels are not much for the reader but rather for the writer: who am I writing to? without such guideline guides vary erratically in quality and content.

The user can explore on his own but he/she will be less frustrated if picking a page written more with his level in mind. Of course that's how all noob users became experts: start reading more complex/expert level books/documentation, nobody stops you from doing that.

See it as when you're cooking and the recipe says roughly what is the level of expertise needed; or when you are playing a game and you choose the level of difficulty. A matching level is a promise of better reader engagement.

But anyway, first we need some documentation :) This idea is about - like wikipedia does - trying to classify docs second possible audience and by attempting to judge their complexity.

Edit: if we had all docs classified, we could for example see that we do not cover very well some type of public and improve existing documentation (or add new) accordingly. It is also true that practically no other Linux distro does this, mostly because of lack of manpower, so you have a single type of documentation that may or may not reach all types of audience.

I think we'd better off identifying use cases rather then users.

When introducing a new concept like use of a tool or shell script link to documentation about that. This way users already familiar with that tool or concept can carry on but those unfamiliar with it have a path to enlightenment.

Daniel

@CenturionDan yes agree with you on that. Will update the issue text

@gdm85 . . . hellekin and I briefly discussed how to make docs more accessible to users. Lists of links to docs in various categories would be really helpful. They could be posted on the new website and possibly on git also.

And possibly off topic here . . . any chance we can have a sitemap for git? git is a labyrinth and I have difficulty finding stuff. The Explore Projects approach (now with those nasty pastel id buttons) doesn't work that well for me. A clearly categorized list would be more useful IMO.

I don't believe in categories, that's so XVIIIth Century :)

But yes, the labels are more for writers to adapt their style and contents to an audience rather than "segment" users. The web will provide easy access to documentation and to the various zones of interest in the gitlab. Still to be determined though.

I think we all agree this discussion is useful. But I guess it would better become part of "how to write documentation for Devuan" kind of thing, rather than an issue. It's because there's not much actionable item we can address to close the issue.

Regarding inspiration from other distributions, I recommend the documentation of ArchLinux (and Parabola) which is to me among the best.