Agreed, I think getting something up at first is more important, however we shouldn’t gyp out on user experience and styling.
5 Likes
I second this. UX is something we should be extremely cognizant about.
2 Likes
Me over here with my uncompleted book that I started nearly a year ago…
3 Likes
There’s motivation to complete it now, eh? 
2 Likes
I’ve started experimenting with Literate Programming over the weekend.
In short, it allows me to merge code and documentation without the normal akwardness that the program code defines the order in which to explain things.
My tool of choice ended up being entangled which has some really nice benefits, especially the 2way sync daemon mode adds QoL.
In short, it extracts (the LP term is to “tangle”) the actual source code that is embedded in markdown into source code files that can be used as normal.
entanlged has support for document generators (currently not mdbook but I’m sure that can be added) to create nicely readable content.
I end up with nix code embedded in markdown, no more copy & paste, no more code & documentation divide. Really sweet 
The intro article to entangled has some basic examples.
Maybe this could be an option for documentation heavy projects like a user manual/ book/ tutorial/ … ?
2 Likes
My only experience with literate programming has been orgmode with my old emacs config.
10/10 experience, I love literate programming. 
Yeah I never found love for org-mode. Markdown is not my favorite but somehow my mind connects it easier to the visual result than most other things. Which feels helpful when I’m trying to convey information to others…
To this day, I can’t explain why I love orgmode so much
It just clicked in that perfect ineffable way and I’ve been trying to replicate that feeling ever since.
At the moment though, I use obsidian for all my note taking because I’m not using emacs anymore. It’s pretty alright 
Can we have a poll of the most common ones on the top level post?
I don’t disagree that this is a good idea but I feel this is more of a place to discuss the options then to settle on the final software.
2 Likes
I would want to highlight one think I’ve noticed while checking Guix: the docs are available on multiple formats, even consumable straight from terminal.
While @imadnyc here has mentioned some troubles with visuals & designs I do believe we can learn a thing or two from them.
3 Likes
I think having multiple forms of docs is quite a good idea, however from the start we should focus on docs consumable via the web and then translate that over to a terminal application or similar.
2 Likes
There may be some amount of forethought necessary if this is an end goal. We could make the decision early to own documentation as markdown files which would make transformation into terminal-accessible help pages more quickly achievable than figuring out how to properly and regularly export an entire wiki.
4 Likes
I think markdown docs should be what we use as a start anyways, it’s easily organizable and many wiki/docs programs support it.
1 Like
In regards to this I think its worth tracking Create a docs website · Issue #156 · catppuccin/nix · GitHub since they plan on having both markdown docs and a fully fledged website. And i think it looks good from what I’ve seen so far.
1 Like
Whoops! I had completely missed this topic and in stead posted here: Documentation Team Goals Tracking Issue - #6 by AngryAnt
TLDR; I would really recommend going with a wiki option which syncs to/from a git repo of markdown files for:
- Keeping an excellend wiki edit & view flow, while also letting people use their generally preferred text edit flow.
- Not binding to a specific wiki software and its db.
- Leveraging broad integration options, dynamically sourcing wiki content and well as easily re-using the latest content in different contexts.
6 Likes
A user on the nixos forums created https://nixlang.wiki/ which syncs the markdown to a git repo of choice. It also supports other stuff like diagrams from draw dot io, SSO, and probably more I’m not aware of. I found it much better to write stuff there than opening a markdown editor, starting a local server to see what the changes look like, iterating, commiting, creating a PR, yadayadayada. The nixlang wiki’s software is https://wiki.js.org/ and is a joy to use.
2 Likes
My bad, is this topic about to use for reference documentation (generated from code?), a wiki for user documentation, what tutorials should be written in, or what the manual should be written in? Or something else altogether?
There’s a good documentation system that django uses About | Divio Documentation and I’m curious what this topic is targeting, because I don’t think the same software can be used for all usecases, especially for wiki type stuff.
1 Like