Documentation for less technical users

[tredondo]

I'm a semi-technical user and on one hand, firejail is pretty easy to use, so it should appeal to many users, but on the other, it uses some very technical terms right from the start, that may turn users off.

About/README

The "About" of this repo for example, is "Linux namespaces and seccomp-bpf sandbox". I have no idea what those are, esp. seccomp. This might scare off some users. Maybe a more general description would be better (e.g. "Firejail - sandbox console or graphical Linux applications"), followed by details in the README?

As a non-technical user, I would much rather see "per-directory access control to the filesystem", but I don't see that in the first 3 paragraphs of the README. "Mount tables" sounds vaguely like that, but that's an implementation detail, rather than a user-facing feature.

A "Features" section would be great. I really think that listing firejail's features at the top of the README could bring many more users to it, and the technical implementation details (whatever seccomp-bpf means) can follow underneath.

Documentation

The documentation is formatted as a man page. This is fine in the terminal, but on the web, this has a few problems:

• no hyperlinks. For example, in firejail-profile, I'm not sure what "netfilter" is. Sounds like a firewall. A link would really help. (This could still be added while keeping the man format)
• monospaced font is harder to read than proportional font, especially with justification:
  
• no formatting (e.g. bold, italics, monospace/tty for arguments)
• less mobile-friendly (useful for users evaluating firejail)

Examples

After some Googling, looks like netfilter can indeed be used to implement firewalling. This is IMO the most common networking profile restriction that a user would want. For example, an application should only be allowed to access a given host, and nothing else. Far more common than mtu or setting a different hostname for the sandbox. So an example for that would really help.

[kmk3]

I'm a semi-technical user and on one hand, firejail is pretty easy to use,
so it should appeal to many users, but on the other, it uses some very
technical terms right from the start, that may turn users off.

About/README

The "About" of this repo for example, is "Linux namespaces and seccomp-bpf
sandbox". I have no idea what those are, esp. seccomp. This might scare off
some users. Maybe a more general description would be better (e.g. "Firejail

• sandbox console or graphical Linux applications"), followed by details in
  the README?

Having an additional explanation using simpler terms would be nice.

As a non-technical user, I would much rather see "per-directory access
control to the filesystem", but I don't see that in the first 3 paragraphs of
the README. "Mount tables" sounds vaguely like that, but that's an
implementation detail, rather than a user-facing feature.

Yes, this is a rather key feature of firejail and would be nice to have it
explicitly mentioned/a high-level explanation.

A "Features" section would be great. I really think that listing firejail's
features at the top of the README could bring many more users to it, and the
technical implementation details (whatever seccomp-bpf means) can follow
underneath.

Agreed.

Documentation

The documentation is formatted as a man page. This is fine in the terminal,
but on the web, this has a few problems:

• no hyperlinks. For example, in
  firejail-profile,
  I'm not sure what "netfilter" is. Sounds like a firewall. A link would
  really help. (This could still be added while keeping the man format)

• monospaced font is harder to
  read
  than proportional font, especially with justification:
  

• no formatting (e.g. bold, italics, monospace/tty for arguments)

• less mobile-friendly (useful for users evaluating firejail)

(Possible duplicate of #2729)

To me it is important to have the documentation promptly available in the
terminal and, as you have noted, the problems raised are essentially a matter
of formatting in the html output. For some fancy conversion examples, the
following html pages were generated from the find(1) man page:

• https://man.archlinux.org/man/core/findutils/find.1.en
• https://man7.org/linux/man-pages/man1/find.1.html

Since it's the version from GNU's coreutils (or "findutils" in this case), the
source is probably in groff and the output does have hyperlinks (e.g.: to other
man pages) throughout.

mandoc also supports all of the items. Examples from its own mdoc-written
documentation and from OpenBSD's documentation (which also uses mandoc),
respectively:

• https://mandoc.bsd.lv/man/mandoc.1.html
• https://man.openbsd.org/man.1

firejail-profile,

Note that this website is not official/released yet, and that the progress is
being tracked on #2729. Looking at the source code, the html file seems to be
generated from a markdown file, which contains just a text dump of the
formatted man page, wrapped in a code fence:

https://raw.githubusercontent.com/rusty-snake/firejail/4906551540196cc3f4a240b5715faf5ea7f45569/features/man-firejail-profile.md

I don't know how the roff to markdown conversion was done, but using groff
directly gives a rather normal-looking html page:

$ zcat /usr/share/man/man5/firejail-users.5.gz |
  groff -T html >firejail-users.5_groff.html

It has a non-monospaced font and formatting, but it does not appear to be
exactly mobile-friendly. It's also HTML4 (which I'm not sure how much it
matters in practice). There are no hyperlinks because they are not marked as
such on the roff source. Also, converting firejail-users(5) results in a
rather botched output (half of the page is bold):

$ zcat /usr/share/man/man5/firejail-profile.5.gz |
  groff -T html >firejail-profile.5_groff.html

I suspect that it may be due to an unproperly-formatted source. In that case,
the first step towards good-looking html output would likely be to fix the roff
input.

Additionally, another option would be pandoc:

$ zcat /usr/share/man/man5/firejail-users.5.gz |
  pandoc -T html >firejail-users.5_pandoc.html
[WARNING] This document format requires a nonempty <title> element.
  Defaulting to '-' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

It's HTML5 and it at least has this (for mobile friendliness, etc):

<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />

Though it appears to miss/ignore some elements and I'm not sure if it's due to
problems in the source or in the conversion.

[rusty-snake]

"Linux namespaces and seccomp-bpf sandbox"

are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect.

A "Features" section would be great.

👍 👍

The documentation is formatted as a man page.
Additionally, another option would be pandoc:

If did some research and testing for man-pages written in something more comfortable then (g)roff in the lat weeks, if we want, we can also switch to md/rst/ronn/pod/... as source and then convert it to groff/html/latex/...

Documentation for less technical users

Related: #2977

[tredondo]

Thanks for addressing my suggestions, related question: where does the documentation for the Features page live?

I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR.

[rusty-snake]

where does the documentation for the Features page live?

On wordpress

I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR.

Not possible ATM you need to ping @netblue30 so he can update that page, read #2713 (comment).

[netblue30]

@tredondo - just put it here in the discussion and I'll move it on wordpress. You will probably find a lot of them, most of us here are not native Engilsh speakers. Thanks.

[rusty-snake]

@netblue30 it's already here, /etc/firejal misses a i.

[netblue30]

I got it, thanks!

[tredondo]

"Linux namespaces and seccomp-bpf sandbox"

are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect.

I came back to firejail after half a year, and still have absolutely no idea wtf seccomp-bpf is :) And the README still starts with that gibberish.

[tredondo]

Back to firejail after 3 years and it's still cryptic.

Maybe the core team doesn't care about attracting more users?

Maybe they just need a reminder?

Here's a practical one: briefly explain in the README what the deal is with AppArmor vs. SELinux. Users may think it's another security layer/module they can compile support for, and waste time installing libraries to compile support for it, when it may not be supported by their OS.

Seeing the little traction this issue has received, I went ahead and edited the README - #6524. Feel free to fix the obvious mistakes I probably made.