2

I started collecting from users of my project about the problems they face while using it and decided to put it into the documentation. Since right now it's just a single "README" document, I put it together there. The problem is that those are random pieces of advice that IMHO don't justify creating a new section for each of the issues. Because of that, I ended up with a section that looks like the following (context can be found on the GitHub page):

Notes

  1. After having generated a package by aflize, you need to install it. You can run dpkg -i ~/pkgs/*.deb for that. If dpkg complains about missing dependencies, you can fetch them quickly by calling apt-get -f install -y.
  2. Some software is represented by metapackages that point to specific versions of a program. For example, if you want to build Python", you should rather aflize python3.5 ("python3" might not be specific enough either).
  3. If you're running out of disk space or plan to build a big package, keep in mind that by default Docker allocates 10 GiB per container. Read up on how to increase this value if you plan to build, say, libreoffice.
  4. Some packages won't build and this can often be a bug that should be reported to the Debian package maintainers. If the "aflize" failed while performing post-build tests, you can still use the resulting binary. Look for it in /root/pkg directory. You can also apply patches at this stage and try just running "make". Sometimes it's that easy.
  5. If you built a big package, consider submitting it to afl-sid-repo: https://github.com/d33tah/afl-sid-repo. If you're about to build a big package but don't feel like waiting for the process to complete, check this repository out.

Should this be considered bad UX? How could I improve it?

2

If you had infinite time, it'd be better to write these notes up in an organized way with section headers and maybe an FAQ style table of contents at the top.

But you may not have the time, or it may be better spent on other stuff, so the key question is: are users better off with an unorganized collection of helpful tips, or no tips at all?

In this case it looks clearly like the answer is yes, users are better off having the helpful information available even if it isn't organized yet.

Until you find time to organize the tips better, I would group them under a header like "helpful tips from users", and provide a 1 sentence intro to the list like: "These tips have been submitted by users. I have not tested all of them yet but you may nevertheless find them quite helpful".

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.