Marketing Team Meeting Minutes #5

Governance Marketing Team
#1

Another installment of Marketing team meeting is behind us. This time we were very efficient and discussed all the planned topics in one hour.

  • Meeting were attending: @garbas, @domenkozar, @samueldr, @edolstra, @davidak, @aepsil0n
  • Landing page, simpler PR
    • Planning to merge this as soon as possible
    • Look at the PR for latest review link
  • nixos-search
    • this is a replacement for current search for packages and options
    • apart from being on par with current search functionality it also does a better job at finding more relevant results (Hint: try searching for “ghc” and compare the results)
    • preview can be found here: https://nixos-search.netlify.app
    • many other ideas are planned but first we need to replace current search
  • Community survey
    • we need to get to know our community better, survey is one way of doing this
    • until next time @davidak will prepare a more concrete idea and plan of execution since he has been thinking about doing this for quite some time
  • History page
  • Usability testing
    • @aepsil0n did an UX experiment with one person
    • this experiments are not limited only to nix cli, but can be about website, documentation, etc…
    • the experiment is going to be - for now - only announced here on discourse and we will be looking for ~5 participants. once we become more fluent with running this experiments we hope to invite more.
    • we still need to discuss: (1) what do we want to measure (2) how do we collect the results and present them at the end
  • Guides on nixos.org

As always I would invite you to watch the whole meeting to get all the details.

Thank you.

7 Likes
#2

Your discussion on the last big bullet point Guides on nixos.org made me think a bit about the documentation and why I personally have a lot of struggles with it. I’m not sure if it’s just me, but I don’t have any concerns about the documentation tool @domenkozar used for https://nix.dev. The reason I think https://nix.dev won’t help making NixOS any more “mainstream” is that it’s pretty much just redundant information.
My experience with the probably best documented distribution (Archlinux) is that there is one wiki which will tell you all the things you need. While using Archlinux (and Manjaro) the archwiki was the only official documentation I ever needed. I want to install it? Arch wiki has one installer page. I want to create a new package? Arch wiki has one “how to add a package” page.

For NixOS, it seems to be the exact opposite. There is not just one page explaining how to do stuff, there are many.
Two very basic examples:

When I google “Install NixOS” I initially get the NixOS Manual (which I think is good). But then the third link in the installation guide links me to https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media “for a number of alternative methods” if I don’t want to use a USB. A second installation guide? Why is not just everything in one place?

When I google for “NixOS create package” the first 3 results are Nixpkgs manual, Nix Manual, Nixos wiki: https://nixos.wiki/wiki/Packaging/Tutorial. If I had never created a nix package before I would definitively klick on the Packaging Tutorial Link, as it’s the only one with “Packaging” in the name. And what do I get when I open the page? Links to the Nix Pills, the Nix Manual and the Nixpkgs Manual. What am I expected to do to get the Informations I need? Read this page, the nix pills, the nix Manual AND the Nixpkpgs manual?

Another thing I realised (while writing this comment) is that the wiki is unofficial and therefore sometimes quite poorly written, to the point that it’s stating that it may be outdated/wrong. False information (a.k.a. tutorials that don’t work) can surely be a reason some users don’t stay. I’ve seen that there is a maintainer team for the archlinux wiki. We may also find people to build such a team and make the wiki official? The Manuals could then also become a part of the wiki and I’m sure we could find a solution to be able to present them both as a one pager (for those who can’t miss them) and as separate wiki entries per topic. If we then want Manuals on different use cases we’d have for example one wiki page called “Docker” with different subtitles for e.g. “Nix in Docker” or “building a Docker image with Nixpkgs” (hey that’s already the case!).

5 Likes
#3

One solution I proposed here was -NixOS- code vs wiki vs manual - having no wiki and manual PRs are triaged separately, this keeps a single source of truth, maintains quality and keeps things versioned.

1 Like
#4

Oh I missed this topic completely :open_mouth: I guess any further discussion about this makes more sense in your thread :slight_smile:

#5

I hope before replacing the current search pages the ability to sort is added(or the default sort order changed to alphabetical). Not being able to sort the results makes the options search quite a bit less useful than the current tool.

For example, if I am configuring a service, having all the options related to that service grouped together is fairly important. Sorting is even more important when the module supports submodules.

The preview also seems to have some significant bugs. Is that running off the current code? Should I be opening github issues for bugs present in the preview?

1 Like
#6

We are moving into that direction. Let me explain…

One focus of marketing team is to present information on the website in a way that it can be easily discovered. Be it documentation or something else. But as we can agree documentation is something very important in a project like Nix.

While there is no documentation team currently there is quite a lot of different efforts in regards to documentation. We could wait for RFC 64, where a format / tools are being discussed, to be resolved or we can also move ahead and produce the content that we think is missing for newcomers. This will come in form of guides / tutorials (eg. Build docker images with Nix, …).

Hope this answers some of your concerns. What I think is important that we move step by step (eg. tutorial by tutorial) otherwise the size of the effort needed will wear us down.

#7

Thank you for looking at the preview.

I hope before replacing the current search pages the ability to sort is added(or the default sort order changed to alphabetical). Not being able to sort the results makes the options search quite a bit less useful than the current tool.

Sort is definitely possible to add, but we are first focusing on implementing bare minimum and replace current search. What will follow shortly after is an option to drill down your search results. eg. searching for requests should present you with different pythonXYPackages versions that you can search in.

For example, if I am configuring a service, having all the options related to that service grouped together is fairly important. Sorting is even more important when the module supports submodules.

At the time of writing we only focused on having packages search yield better (more relevant) results. We are yet to look at options and how to make that search better.

The preview also seems to have some significant bugs. Is that running off the current code? Should I be opening github issues for bugs present in the preview?

I would wait until the search.nixos.org is going to be announced and then report bugs. Currently things are still in a bit of flux and there are also things that are still planned before we called it a release. Time wise I think we will be have first release in next 2 weeks.

#8

I might argue that having the option search be at least as usable as the current search should be part of the bare minimum. Even if you don’t all the bells and whistles implemented, at least don’t apply a relevance sort to it as you would a package search.

EDIT: After reading this the next day, I realized it may come across more sarcastic than I intended depending on how you read it. @garbas, I want to be clear that it was not my intention to be overly critical and I appreciate all the work you guys are doing. I just wanted to point out that something I felt was important was at risk of being lost as it was looking at that point in time. I apologize if I did poor job of communicating that.

4 Likes
#9

Yeah I understand that it will need the RFC64 to be merged before we can decide on one place for all the documentation. It‘s just a bit confusing to me that the temporary decision is to create another place instead of using the wiki. But I guess I‘ll just accept that and wait for the RFC to be closed in hope that we can then move on to merge all our documentations to have them at one place afterwards.

#10

As long as the smart sorting only puts some „important“ packages at the top and leaves the rest sorted alphabetically, I don‘t see much of a problem. The difference to the old search isn‘t that big.
But I noticed that the new search matches less packages. e.g. wpg will only match libwpg in the new search while it also matches wpgtk in the old search.

On another note: @garbas have you ever thought about adding Github Issue/PR/commit infos to the search? It would sometimes be useful to know if there is an open ticket for a package, or which was the last changing commit, etc. :slight_smile: I would really love if such a feature would be in the backlog!

#11

Would it at that point not be better to set up a platform such as https://tracker.debian.org ?

2 Likes
#12

How exactly would that be better than using an existing, mature platform? The only reason Debian is rolling it’s own is probably that it predates the GitHub era. Not that I‘m a fan of GitHub in particular - it’s just there and it works.

#13

I think there is some misunderstanding here. The comment by @Melkor333 is about adding references to GitHub issues on a NixOS search page, it’s not about extending GitHub with functionality we need. The Debian Tracker is also not an issue tracker, it’s about collecting all relevant information of a package in an overview.

1 Like
#14

Well yeah, actually I already made a thread about exactly that some time ago. :smile:
But in my eyes the debian tracker and the nixos search are not far from each other. The nixos search platform could slowly be transformed into a tracker by adding more and more tracking information to it :stuck_out_tongue:
And given the NixOS search is actively improved the chances it‘ll get some tracking features are higher than the chances somebody creates a specific tracking platform…

#15

@FRidh @Melkor333 Evolving search.nixos.org into what tracker.debian.org is an option. I added some ideas I’d like to explore in the here.

2 Likes