<matthewcroughan>
the fact that this is in a database on someone's computer is crazy, it's just docs
<samueldr>
that's, like, your opinion
<matthewcroughan>
I understand the need for a database when it's a massive forum, like Discourse.
<samueldr>
a bit rude to jump in and directly jump to "not like I want to do it so it must be bad" :/
<matthewcroughan>
But putting docs and things like that behind a database, and hiding it from Git (makes attributions less rich and meaningful), makes it a bit weird and anti-nix in a way.
<matthewcroughan>
samueldr: not what I'm saying at all, I can see the advantage of it having its own user system, but this is in my opinion just going to be a nightmare if the docs are under the control of an individual
<matthewcroughan>
How can I host/compile the wiki myself?
<matthewcroughan>
Is the database given out to people?
<samueldr>
the data is, I don't remember how at the time being, but it is freely available
<samueldr>
the setup itself, the user who contributes hosting and managing it hasn'g gotten around to extracting the configuration
<matthewcroughan>
as long as it's something I could run on my machine with minimal effort, I'm happy
<samueldr>
(mainly secrets were an issue IIRC)
<matthewcroughan>
but it seems like a lot to give away for the small advantage of making user contributions easier.
<samueldr>
but that user hasn't had the time to do it
<matthewcroughan>
Having anything less than static pages for Docs just seems wrong to me. It's an opinion, sure, but I can make a lot of very good arguments for it.
<matthewcroughan>
I'm going to pay attention and look for opportunities to improve this, I'll use this for now.
<matthewcroughan>
samueldr: have you seen docusaurus?
orivej has joined #nixos-wiki
<matthewcroughan>
samueldr: what does the constant `|-` mean in the docs?
<matthewcroughan>
I'm confused by nothing but that
<matthewcroughan>
This is what you get when you have too much control over the docs and no framework like Sphinx/MkDocs. And I know that Sphinx/MkDocs can be limiting in certain contexts>
<makefu>
https://documentation.divio.com/ just came around yesterday again. It is a reminder, that there cannot be a single source of documentation but there need to be different types for different use cases. the wiki is mostly problem oriented where the manual is more explanation and reference oriented
nixoswikibot has quit [Remote host closed the connection]
nixoswikibot has joined #nixos-wiki
srk has quit [Remote host closed the connection]
srk has joined #nixos-wiki
nixoswikibot has quit [Remote host closed the connection]
nixoswikibot has joined #nixos-wiki
orivej has joined #nixos-wiki
<matthewcroughan>
Mic92: I would just like a place for board docs that is not hidden behind a database.
<matthewcroughan>
I'd make it in mkdocs, but obviously I can't maintain that alone.
<ryantm>
With mmdoc I'm using cmark-gfm which is mostly standardized plus a few github extensions plus a very minimal form of bracketed spans (just anchors)
<ryantm>
Oh I guess I added did lists and admonitions too 😞
<ryantm>
DD lists
<matthewcroughan>
Sweet :)
<matthewcroughan>
ryantm: I will take a look at contributing after work today
<matthewcroughan>
Is there a way I can submit the Orange Pi 3 docs today? Or is this thing not public yet?
<ryantm>
Oh and the time to rethink using Markdown is basically over. We don't want to have to relive the RFC process of https://github.com/NixOS/rfcs/pull/72
<{^_^}>
rfcs#72 (by mboes, 29 weeks ago, merged): [RFC 0072] Switch to CommonMark for documentation
<matthewcroughan>
If I want to submit my docs in this fashion, what do I do?
<ryantm>
You can submit markdown docs in nixpkgs already. You'll need to write like one line of DocBook to get it integrated.
<ryantm>
The instructions in those issues would basically work for adding new docs.
<matthewcroughan>
ryantm: would you accept markdown docs for boards and board support in general?
<matthewcroughan>
ryantm: is there an example set of docs for boards even?
<ryantm>
Looks like there isn't a boards section yet. Are you documenting something in nixpkgs?
<matthewcroughan>
ryantm: nope, I just wanted to document getting NixOS running on the Orange Pi 3.
<matthewcroughan>
But don't really like the idea of contributing to nixos.wiki because it's in a format I really don't think will last
<ryantm>
matthewcroughan that sounds more like a NixOS manual thing and it does not support markdown yet.
<ryantm>
That's why I'm building mmdoc.
<makefu>
matthewcroughan: you do not have to worry about the wiki this time at least. fadenb is preparing to open up the configuration of the wiki deployment so at worst case someone else can take over the instance.
{\_\} has joined #nixos-wiki
{\_\} has quit [Remote host closed the connection]
<matthewcroughan>
ryantm: yes, so is there an example of mmdocs being used to describe a board yet?
<matthewcroughan>
Whatever the case I'll try and figure it out and make that example.
orivej has quit [Ping timeout: 272 seconds]
nixoswikibot has quit [Remote host closed the connection]
nixoswikibot has joined #nixos-wiki
<ryantm>
matthewcroughan I haven't integrated mmdoc with the NixOS manual yet. Also, there hasn't been widespread consensus we should use it.