clarify wiki purpose for new users #34

Open
opened 2024-12-17 12:57:35 +00:00 by benaryorg · 4 comments

I have stumbled upon the Lix wiki several times when looking for information not contained in the regular Lix docs, among them meta-issues such as Nix lang v2.

It is unclear to me, as someone who is not part of the Lix Matrix environment, what exactly the wiki should hold in terms of information, and more importantly who is allowed or supposed to edit it.
Also tying in with this, I do not think either Matrix or Bookstack to be particularly good at allowing publicly visible discussions to be held in a traceable way as I think a Wiki should be both for user provided content serving as a source for unofficial information or volatile as well as having discussions related to said content right next to it.
So with the lack of the discussion portion I feel very uncomfortable editing the wiki for any reason other than fixing typos at best, even if it is information fitting the topic of the page since I am not sure whether I am supposed to, or whether it's the right place (i.e. I can't add "should we add a section for $thing here?" as a discussion item).

Matrix on the other hand, being more of a group chat at heart is great for asking questions, but as we all know instant messengers and group chats are not a replacement for a wiki or forum.1 2 3 4
Even when the wiki is telling me to join the discussion on Matrix I cannot see whether I'm the first, tenth, or hundredth person saying the same thing, unlike for example the NixOS discourse (one of the first things implemented by the auxolotl project), which large leads to me just not participating at all.
This is something that IMHO is one of the primary purposes of a Wiki, therefore any guidance of whether or not the wiki is supposed to handle that kind of information would be useful.
Bookstack kinda lacks the usual wiki features for the discussion part, unless you start creating a talk page for every bookstack page or explicitly state how to provide discussion content inline.
IIRC bookstack support both HTML comments as well as Notice/Warning banners, so creating a notice banner for "there is a discussion about $thing in the below paragraph" with the discussion happening in an HTML comment within that notice would work, but it doesn't feel well done either.
Confluence back where I used to work had that inline comment and discussion feature, but Confluence isn't a thing for other reasons anyway.

With all that said, what is the wiki supposed to contain, and who is supposed to edit it, and can someone add that to the wiki in a way that is very visible and clear (a book called "welcome to the wiki" or "getting started on the wiki", etc.)?
It would also be nice to have the community section of the Lix website even list the wiki at all.

If required I can split off part of this into a second issue for "more accessible and public discussion spaces" or similar to move my complaints about Matrix to.

I have stumbled upon [the Lix wiki](https://wiki.lix.systems) several times when looking for information not contained in the [regular Lix docs](https://docs.lix.systems/manual/lix/stable), among them meta-issues such as [Nix lang v2](https://wiki.lix.systems/books/lix-contributors/page/nix-lang-v2). It is unclear to me, as someone who is not part of the Lix Matrix environment, what exactly the wiki should hold in terms of information, and more importantly who is allowed or supposed to edit it. Also tying in with this, I do not think *either* Matrix *or* Bookstack to be particularly good at [allowing publicly visible discussions to be held in a traceable way](https://www.explainxkcd.com/wiki/index.php/Talk:3023:_The_Maritime_Approximation) as I think a Wiki should be both for [user provided content serving as a source for unofficial information or volatile](https://wiki.nixos.org/wiki/Rust) as well as [having discussions related to said content right next to it](https://wiki.nixos.org/wiki/Talk:Rust). So with the lack of the discussion portion I feel very uncomfortable editing the wiki for any reason other than fixing typos at best, even if it is information fitting the topic of the page since I am not sure whether I am supposed to, or whether it's the right place (i.e. I can't add "should we add a section for $thing here?" as a discussion item). Matrix on the other hand, being more of a group chat at heart is great for asking questions, but as we all know instant messengers and group chats are not a replacement for a wiki or forum.[<sup>1</sup>](https://djarodonk.medium.com/stop-using-discord-for-wikis-faqs-and-other-knowledge-bases-9085223a514b) [<sup>2</sup>](https://www.reddit.com/r/slatestarcodex/comments/1260up9/essay_stop_using_discord_as_an_archive/) [<sup>3</sup>](https://malenfant.net/@didier/112528487189999791) [<sup>4</sup>](https://www.pcgamer.com/please-stop-making-discord-servers-for-things-that-shouldnt-be-discord-servers/) Even when the wiki is telling me to join the discussion on Matrix I cannot see whether I'm the first, tenth, or hundredth person saying the same thing, unlike for example [the NixOS discourse](https://discourse.nixos.org/) ([one of the first things implemented by the auxolotl project](https://forum.auxolotl.org/)), which large leads to me just not participating at all. This is something that IMHO is one of the primary purposes of a Wiki, therefore any guidance of whether or not the wiki is supposed to handle that kind of information would be useful. Bookstack kinda lacks the usual wiki features for the discussion part, unless you start creating a talk page for every bookstack page or explicitly state how to provide discussion content inline. IIRC bookstack support both HTML comments as well as Notice/Warning banners, so creating a notice banner for "there is a discussion about $thing in the below paragraph" with the discussion happening in an HTML comment within that notice would work, but it doesn't feel well done either. Confluence back where I used to work had that inline comment and discussion feature, but Confluence isn't a thing for other reasons anyway. With all that said, what is the wiki supposed to contain, and who is supposed to edit it, and can someone add that to the wiki in a way that is very visible and clear (a book called "welcome to the wiki" or "getting started on the wiki", etc.)? It would also be nice to have the [community section of the Lix website](https://lix.systems/community/#engaging-with-the-community) even list the wiki at all. If required I can split off part of this into a second issue for "more accessible and public discussion spaces" or similar to move my complaints about Matrix to.
Owner

@benaryorg Hi there, thanks for the message. We should definitely discuss it internally and come back to you, I am sorry, the Xmas period is a bit busy. If I do not answer by mid-January, please can you reping me?

@benaryorg Hi there, thanks for the message. We should definitely discuss it internally and come back to you, I am sorry, the Xmas period is a bit busy. If I do not answer by mid-January, please can you reping me?
Owner

https://wiki.lix.systems/books/lix-contributors/page/information-organisation This page is the current official documentation of what the various information areas are for. It definitely needs some updating since it was written during the Lix private beta period.

It is true that the wiki is bad at being a forum. The wiki exists for development process information which is slightly more stable than a pad and other things that are not actually reduced to practice yet, and thus do not have proper documentation that would come in a release. We actually do have a Discourse forum deployed for private purposes (which did not quite materialize in the way expected) and probably could use it more, but we do not currently have the resources to actually run it as a public thing, so we do not currently do so.

The wiki does not exist for user facing documentation. It is primarily a low-friction area for developers and basically anyone else who has issue triage access (e.g. the entire private beta group, anyone who has ever submitted any code, the core team) to put things.

It is also true that more planning information should be posted publicly.

I agree that BookStack doesn't have comments; however, it can be treated as if it is MediaWiki and you can write comments inline in the page content as people usually do on pads, especially on the most WIP pages. It is not supposed to be polished, and it can be treated as such.

https://wiki.lix.systems/books/lix-contributors/page/information-organisation This page is the current official documentation of what the various information areas are for. It definitely needs some updating since it was written during the Lix private beta period. It is true that the wiki is bad at being a forum. The wiki exists for development process information which is slightly more stable than a pad and other things that are not actually reduced to practice yet, and thus do not have proper documentation that would come in a release. We actually do have a Discourse forum deployed for private purposes (which did not quite materialize in the way expected) and probably could use it more, but we do not currently have the resources to actually run it as a public thing, so we do not currently do so. The wiki *does not* exist for user facing documentation. It is primarily a low-friction area for developers and basically anyone else who has issue triage access (e.g. the entire private beta group, anyone who has ever submitted any code, the core team) to put things. It is also true that more planning information should be posted publicly. I agree that BookStack doesn't have comments; however, it can be treated as if it is MediaWiki and you can write comments inline in the page content as people usually do on pads, especially on the most WIP pages. It is not supposed to be polished, and it can be treated as such.
Owner

I really appreciate the feedback, and these are the easy to improve things that I am thinking we should improve specifically based on your post:

  • More visibly document how people get triage/wiki-edit access, probably on a welcome page (namely, it is manually granted to anyone who submits code or who has generally been active, and it can simply be asked for).
  • Put a welcome page on the wiki that links to the explanation of how things are organized. I am not sure which bookstack feature needs to be used to put that page more prominently.
  • Document the warning/infobox CSS that allows you to visually distinguish a comment like the TODOs as suggested.

Do you think this a reasonable course of action?

We are aware that the matrix is a black hole for information and try our best to treat it as such.

I really appreciate the feedback, and these are the easy to improve things that I am thinking we should improve specifically based on your post: - More visibly document how people get triage/wiki-edit access, probably on a welcome page (namely, it is manually granted to anyone who submits code or who has generally been active, and it can simply be asked for). - Put a welcome page on the wiki that links to the explanation of how things are organized. I am not sure which bookstack feature needs to be used to put that page more prominently. - Document the warning/infobox CSS that allows you to visually distinguish a comment like the TODOs as suggested. Do you think this a reasonable course of action? We are aware that the matrix is a black hole for information and try our best to treat it as such.
Author

Thanks for all the information, it does definitely help figure out what's what (in terms of which system holds what information), much appreciated.
Of course I do have Opinions™ (like thinking the Discourse being public would be great) but given the resources the project has I think the status quo is perfectly reasonable if it is documented well, and hey, I'm not running any project of the magnitude of Lix so I have an easy time talking.

The three points listed sound like a pretty solid documentation, and the only thing missing (IMHO) would be to also cross-link the information organization book/page in the mentioned community section of the Lix website because, like you said, making it more prominent in bookstack isn't quite obvious (if possible), and the website usually is the first thing that people scour when trying to find information on what subsystems exist (that however is highly subjective, maybe it's even just me).

(also no worries about responding later, I know that some if not most of y'all probably have better things to do this time of year)

Thanks for all the information, it does definitely help figure out what's what (in terms of which system holds what information), much appreciated. Of course I do have Opinions™ (like thinking the Discourse being public would be great) but given the resources the project has I think the status quo is perfectly reasonable *if* it is documented well, and hey, I'm not running any project of the magnitude of Lix so I have an easy time talking. The three points listed sound like a pretty solid documentation, and the only thing missing (IMHO) would be to also cross-link the information organization book/page in the mentioned [community section of the Lix website](https://lix.systems/community/#engaging-with-the-community) because, like you said, making it more prominent in bookstack isn't quite obvious (if possible), and the website *usually* is the first thing that people scour when trying to find information on what subsystems exist (that however is highly subjective, maybe it's even just me). (also no worries about responding later, I know that some if not most of y'all probably have better things to do this time of year)
Sign in to join this conversation.
No labels
A-infra
A-matrix
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: lix-project/meta#34
No description provided.