This is going to serve as the tracking issue of the organization of the docs team – what do we do, what do we leave to the community, and how work is delegated. I have some ideas, but I’d like to get some shuteye before I type it up – I’d like to hear some thoughts in the meanwhille.
6 Likes
Excellent, thanks for making this! I’d like some sort of regular SIGDocs calls, perhaps once a week/once a fortnight?
We should figure out when best suits people, perhaps something like https://www.when2meet.com/ could be used to find some good times?
I think this would help us get organized and stay on track for excellent docs – plus in my opinion it is easier to work with people when you can chat outside of a forum every so often
If we do this, we should post minutes to here or a subcategory
4 Likes
Here’s a preliminary look at what my ideal documentation team looks like. It’s still rough around the edges, but I think it’s a good launchpad?
This attempts to patch some of the holes that the old documentation team had, namely manpower. https://github.com/NixOS/nix.dev/tree/master/maintainers
Our general responsibilities are pretty straight forward, so lets talk about:
Things we do to address the shortcoming of nix docs
-
Centralization
-
Efforts should be made to take all the current info linked by the official wiki and put it into one website
-
Third-party guides’ authors should be contacted so that we may incorporate their guides into ours instead of redoing it
-
-
Ease of contributing
- The friction between getting an answer and throwing it up to a wiki should be as close to zero as possible
-
Organization
-
Right now, there are too many categories that aren’t clear and don’t link well to each other for better flow. This should be as simple as possible for users to navigate
-
UI/UX should be improved. Searching through the current Nixpkgs manual is tough without coming into it with a specific question
-
Tentative timeline of events
-
Soft fork the nix docs, and ensure that it’s working at whatever place we want it to be accessible by.
-
Figure out what software we are using and, if needed, migrate all docs to this new software
-
Define the new organizational structure of the docs – do we prioritize start to finish guides, how do we treat snippets of code, how do we handle detailed explanations of the inner workings and simplified versions to get people going. This would be a long community discussion, but its important to get as many voices to get this right, and not cater to people already comfortable with nix.
-
Create sub-groups to delegate work from this new organizational structure (who is in charge of new tooling? of updating old docs? etc.). How do these sub-groups communicate, what time zones are people in, and reflect this in the repo. How do we make sure that the docs reflect what the community want?
Implementation
Sub-Groups
-
Migrating Team → Maintenance Team
-
Responsible for taking old nix docs and migrating it to our own, and updating them if necessary. Also responsible for reaching out to third parties to migrate into our own docs too.
-
After migrating is largely done or slowing down, this is the party responsible for ensuring that new submissions are meeting standards and having power to make final changes to the wiki (so that submissions don’t get stale)
-
-
Tooling Team
- Reponsible for making sure the wiki stays afloat, and create tooling to help pipeline the user getting answer to writing docs
-
Accessibility Team
- Making sure that the most amount of people can access the docs — translations, UI/UX, different formats available, etc.
Each team would be responsible for deciding how they want to communicate with each other (there should be a standardized way for non-team members to interface with the docs team), and there’s no restrictions on how many teams someone wants to join.
Tooling
-
A matrix/whatever chat service bot that lets trusted users in the community (decided by mod team) flag certain messages to be exported for review (so if a question gets answered, it’s already uploaded to a place that other people can search from)
-
Telemetry? It’s hard for people on this team, who are going to be familiar with nix, to know what the beginner needs, and beginners are likely to only start contributing once they stop being beginners, so having a tracker seeing what links are clicked/items are searched after someone visits the page so “read more” sections are automatically generated would help alleviate some pressure. Of course, it would be opt-in/abundantly clear that this is happening, and would be anonymous.
-
A ranked choice voting system for discourse
-
I don’t have anything like a tracking cookie in mind, just something server side that noticed that this user searched this term with the search function in the wiki, or clicked this link after clicking to this page.
Other ideas
-
A video series to help onboard users
- I have a Beginners Guide to Using NixOS guide in the works, and my idea is to make it as concise as possible – there are too many 1hr long videos where 45 min of it is someone typing in the commands instead of giving people the information they need
1 Like
Regarding organisation/structure: I really like Diátaxis. Quoting from their introduction:
Diátaxis is a way of thinking about and doing documentation.
It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.
Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.
My impression is, that one problem of Nix’s documentation is, that it’s not clear where to find the relevant documentation for each of those four needs.
3 Likes
Yup, I think there’s going to be a lot of discussion about how to organize it, but I want to save it for when we get the soft fork up and running and we can really pinpoint the pain points with people who might filter in. I agree that the “finding info” issue is pretty bad right now, and a lot of reading source code has to be done.
3 Likes
Re: Doc tech: I really enjoy standardising on markdown files. There are excellent options out there of wikis with regular on-page edit flows which then push to & pull from git versioned markdown files.
We have really enjoyed that flow over the years as it keeps lots of options open both for authoring and integration, without compromising on the core wiki flow.
Re: Matrix chat bot: If something not-off-the-shelf is needed, currently at my day job I’m maintaining and working with a Matrix client API library, written in strict, lean, and performant C#. We publish it under MIT and I would gladly spend some time spinning up a new (well-commented) bot to cover needs here. It obv. builds via nix and runs on NixOS out of the box.
2 Likes