I’m not a technical writer by trade. The SilverBullet documentation and website never had a proper design, it grew largely organically.
It’s become quite clear that for more people to learn SilverBullet and to make it more accessible to a bigger audience, documentation is a blocker.
So let’s talk about how to improve it.
A few questions:
Do you have good example of documentation for similar projects that I can model this after?
Do you have ideas of a specific website structure that would be a good fit. Should this be very feature-by-feature, be more driven by guides, specific use cases. UI element by UI element?
Is there any particular area of docs that you’re missing?
I’d like to use SilverBullet features to showcase SB features. That already happens a lot in the docs right now. Therefore it would make sense to come up with a proper tagging system, for instance, and to use queries to link to other parts of the docs in clever ways.
There’s a bunch of functionality in the Std library, all as meta pages. Some of these are quasi-self documenting: the documentation of the feature and its implementation are “mixed”. I think this is kind of cool, but I’m not sure it’s discoverable or intuitive to people. Also, because these are all meta pages, they don’t appear in the regular document picker on silverbullet.md. Example of what I’m talking about: Page Templates
Let’s collect what are we missing to cover what and how can propagate into the documentation:
FAQ - Frequently Asked Questions (suggest how to do things very often asked about)
BCP - Best Current Practice (suggest how to do certain things the right way)
RFC - Request for Comments (suggest documentation improvements)
TIL - Today I Learned (share, in concise form, user experience or solutions)
howto - more complex things (deployment etc.) - no 3-letter abbreviation though
This forum can be great source to dig up some good base for all of these but…
Some questions repeat almost regularly whenever new user arrives (FAQ).
Some are more rare but solutions should be encouraged to be followed (BCP).
TIL should be separate (probably moderated) category with given rules here in the forum and something from it can propage further to the FAQ and BCP through the RFC.
RFC should live as GH discussion, I think (quite common practice).
Howto is not exactly a documentation and I think it belongs to something like “blog”.
I really like the codemirror reference and as someone who is working on plugs a lot, it would be very useful to have something similar. Most things already have jsdoc comments anyway, so I don’t think it would be too hard to generate, maybe something to consider after switching to nodejs, there are probably tools for that anyway (Unsure what codemirror uses). Could even be a markdown file. This would also be useful for the space lua API, as it would remove the inconsistency between the docs and the actual API, which sometimes arise, although this is probably harder to generate.
Thinking about this further, maybe it actually makes sense to integrate the lua api documentation into SB directly, this could then be shown in hints, similar to most language servers and then such a doc page could probably be generated using space lua. Unsure what this would look like exactly
(Obviously this is only a small part of the documentation)
@MrMugame While talking things like that what is supercool is for example how Mox mailserver’s source code cross-references to exact point in RFCs… example. I love that!
Imagine that you could cross-refer between SB source code and the docs. E.g., docs would be stating “something” is supported and you will see where exactly is the particular “something” implemented in the code (some entrypoint to dig deeper into it, if needed). That would also be splendid.
My suggestion is that Making SilverBullet Documentation More Accessible for Non-English Speakers
First of all, I want to say that the Documents created with SilverBullet’s own features are truly impressive. I really appreciate how the tool is being used to showcase itself.
That said, I’d like to point out one area where I personally feel some inconvenience.
Since neither I nor many of my friends are very proficient in English, we often rely on the browser’s built-in translation function when reading technical documentation. Unfortunately, this doesn’t currently work on SilverBullet pages. (Interestingly, back in v1, when using the Preview feature, browser translation did work.)
I don’t mean this as strong criticism, but I do think it highlights a fairly big challenge for non-English speakers. While I don’t think simply bringing back the v1 Preview feature is necessarily the best solution, I believe it would be valuable if there were some mechanism that allows people—regardless of their native language—to at least use automatic translation when reading the documentation.
This could make SilverBullet’s excellent documentation accessible to a much wider audience and help lower the barrier for newcomers.
multilingual documentation and application (Yes, it would also be good to have SB in other languages)
documentation that shows concrete examples (code + result) as it does now;
a dark theme for my dev eyes
The BEST solution for me is to generate documentation from tests. It’s a win-win solution, as it ensures synchronisation between functional specifications and SB’s actual behaviour, while reducing the effort required for writing and maintaining documentation.
Must say first contact with SB, was a bit unsual.
Yet I’m quite confident SB will adress most of my purpose and I find more an more natural to catch ideas, notes, sketch and concept in SB.
Thanks for all the community making an amazing work on this project
Documentation should provide
A good navigation system that helps to understand what it covers (from concept to personnal theming) in the landing page and ability to quickly focus to your main concern in three step.
Example for each topic with minimal code/data
Getting started (more or less the actual landing page of the doc)
Provide Cheat Sheet (very helpfull when you’re not spending 100% of the time in this project, know that something is possible but do not remeber how)
Migration / compatibility / comparison (choose the one you like) with other project (obsidian, logseq,…)
Installation docs (already done)
→ One of my favorite open-source doc is Grist Help Center, it is not directly based on the code and guess it requires energy to keep this up to date.
I also think it is important to keep those navigating system available anywhere from the doc site, since when discovering the doc, you may want to quickly switch from a them to another.
So it is nice to have at the same time a global view of the doc and a specific topic.
I’m more of a visual person. Of course a solid, complete written documentation is essential (so people can look things up), but what would really help newcomers to Silverbullet is video tutorials demonstrating different workflows. I know video tutorials are harder (or practically impossible) to keep up-to-date compared with written docs, but they can ignite curiosity about Silverbullet’s “hidden” capabilities - features you only discover when you start writing a few lines of Lua or using queries templates and widgets.
It might make sense to include a dedicated section in the docs for video tutorials. For many users, watching a short video is more approachable than wading through pages of text.
For example:
v1 – SilverBullet features:
v1 – SilverBullet deployment using Docker:
And of course all your video tutorials you have already made for v1 (was one of the reasons I chose silverbullet for my note taking) - your videos made me curious and opened my eyes of silverbullets great potential.
A few other improvements could also make the documentation more approachable:
Break documentation into modules matching the mental model of the user:
- “Basics / Getting Started” (install, interface, pages)
- “Linking & Navigation”
- “Queries & Templates”
- “Built-in Commands & Widgets”
- “Available Plugs” a curated list of featured Plugs
- “Space-Lua and Custom Commands/Widgets Scripting” - why not with ChatGPT prompts & examples on how to Lua without knowing any Lua
This helps users not feel lost in “everything at once.” This would also create a clear “beginner to advanced” path and can ease the use of the beginners in not to be overwhelmed by silverbullets “pro” features
Side-by-side code + output examples for queries and templates.
Short recipes for common use cases (like task dashboards or recent notes).
Since v2 removed many “old” features and refocused on Lua, documentation must have a more thorough migration guide from v1 to v2
That way the docs can stay complete and precise, while newcomers get a gentler, more visual way in.
I just want to hard +1 @JmiXIII 's suggestion : Cheat Sheet
This software is amazing, but due to the fast development (which is great, don’t get me wrong haha) and quite evolving features a lot of past problems are not solved the same way, especially since v2, and a lot of thing are actually eazy to do but basically unknown.
For exemple I found nowhere how to just print just the result’s count of a query, i thought it would be in the select part, therefore read that part of the docs three times, to make sure it wasn’t written there. I ended up creating a lua function to do it, and only learned later that i could just put a # before the query… it’s great, but how am i supposed to know it ?
A cheatsheet with all those kinds of thing would be really cool
And implementing silversearch or some other kind of full space search is mandatory in my eyes, right now the search just give you link to pages that contains your query, you then have to search again in the page, and you don’t even have a preview, silversearch does that.
IMO an exhaustive and searchable list of all features is the most important thing to do for the documentation right now
now this is a GREAT software, and i just want to thank you and all the contributors, i could not take notes without it
(thanks for the vim mooooode)
(@costalfy there is already a dark mode, use the command “toggle dark mode”)
For Zef’s 1st question, one might consider a two-part documentation with 1) a tutorial and 2) an exhaustive reference, for example https://typst.app/docs (this 2-part pattern is seen in many other projects, e.g. the TikZ package of LaTeX).
In the first part, some working examples that are conceptually subtle but technically easy can be walked through, aiming to provide the reader with the ability to “separate the wheat from the chaff” when they consult the reference.
The reference can grow more spontaneously if the user can navigate it, and whether they can depends on how well the tutorial is written.
For Zef’s 2nd question, I think the tutorials can be a bit long and be explicitly listed on the landing page of SB, while the technical references can be a flat knowledge garden with no folders and just stand-alone pages connected by wikilinks and organized by tags. It would be helpful to have an exhaustive table of contents for the reference, though, perhaps implemented as a live-query page.
I second the tagging system idea! I learned a lot from just clicking on tags in the SB docs and seeing where they lead me.
Another benefit of organizing with tags instead of folders in the docs is that one may brain-dump into a page first, and associate it with a topic after writting, thus removing the “writer’s block of not knowing where to put this bit of text”. It also enables the docs to grow freely in a flat structure.
I love Grok Tiddlywiki - it’s a hands-on tutorial for Tiddlywiki (that I find is a bit similar to SB) that takes a complete beginner through the concepts and specifics of the application. It’s interactive and full of practical examples.
I would love to see something similar for Silverbullet.
