Jose Quesada (Feb 20 2022 at 03:10): Jose Quesada (Feb 20 2022 at 03:10):Has the team ever considered alternative methods of writing documentation? Especially in the from of live documents?
I am a huge fan of projects such as Notion, where you can reference other notes, and if they change, your references change with them.
There are open source alternatives, such as Dendron which uses VS Code as it's platform. Something like this would make it super easy to find all relevant documentation for the entire project and sub projects. I might even make a good addition to the editor (I'm down to implementing it)
Jose Quesada (Feb 20 2022 at 03:12):I mention this in the context for documenting the Roc project, but could also work for code documentation
Richard Feldman (Feb 20 2022 at 03:25):I have no experience with it, but I'm interested!
Jose Quesada (Feb 20 2022 at 03:39):Here's a link to the Dendron project. All you need to do is open VS Code, install the extension and the just press ctr + shift + P and type dendron tutorial.
In the case of Dendron, it works by creating markdown files with some small amounts of metadata, but then allows you to organize your notes, or whatever, in crazy ways, allowing you to create references to other notes, which in turn reference other notes, and if any of those dependencies change, everything referencing those documents gets updated, helping to greatly mitigate stale documentation.
Jose Quesada (Feb 20 2022 at 03:40):Notion was the first place I came across that introduced me to the this world. It's not open source, but very easy to use. Most of these tools, that I've seen, use markdown syntax.
Jose Quesada (Feb 20 2022 at 03:44):rustdoc has a support for this, although in a much more limited, in the form of documentation references to items in the source code. If an item changes, and some documentation references that item, you get a warning from rustdoc. Even such a small feature is a lifesaver when documenting code
Anton (Feb 20 2022 at 08:50):Very cool, these auto-updating code references in comments is something I wanted.
Anton (Feb 20 2022 at 11:20):@Jose Quesada what do you consider to be the key advantages over using regular markdown files?
Jose Quesada (Feb 20 2022 at 16:14):@Anton Could you elaborate on what you mean by advantages of using regular markdown?
If you mean solutions, such as Dendron, then there are none, because they are just markdown files.
If you mean for code documentation generation, since we're working with the AST, it would be very easy and straightforward to either develop our own live reference support, or integrate with an existing one.
If you mean for documenting everything in the Roc project, the advantages are as follows:
docs folder.This latter point can be remedied by rendering out a snapshot of the documentation every so often, into either a static site that can be hosted on GitHub Pages or as just static, pre-linked Markdown files
Jose Quesada (Feb 20 2022 at 16:17):Also, I think this should be moved to Ideas, I meant to put it there, but placed it in Beginners by mistake
Anton (Feb 21 2022 at 08:06):I somehow can't move this topic to a different stream :thinking:
Anton (Feb 21 2022 at 08:15):I'd like to try this out, what do you think @Richard Feldman?
Notification Bot (Feb 21 2022 at 12:49):This topic was moved here from #beginners > Documentation Idea by Richard Feldman.
Richard Feldman (Feb 21 2022 at 12:51):so we have some part of this already, in the sense that if you run roc docs Foo.roc then it reads the doc comments (comments that start with ##) as modified markdown and generates HTML documentation from them.
Richard Feldman (Feb 21 2022 at 12:52):currently the markdown is modified in one way: when you write something in square brackets - e.g. [List.map] - it treats it as a code link, and goes and looks up List.map in the module's scope (based on its imports) and generates a link to the appropriate documentation for it
Richard Feldman (Feb 21 2022 at 12:53):since we're working with the AST, it would be very easy and straightforward to either develop our own live reference support, or integrate with an existing one.
developing our own sounds more appealing to me at this point
Richard Feldman (Feb 21 2022 at 12:54):I don't want people to have to install a third-party tool to access roc documentation (the roc binary should be all you need!) so if we're integrating the viewing support into the editor anyway, it seems worthwhile to allow ourselves control over the format too
Richard Feldman (Feb 21 2022 at 12:55):markdown seems like a good starting point because it's so widely known, which reduces the barrier to entry for people to write docs, but I like the idea of making our own modifications to it like the [List.map] links we already do
Richard Feldman (Feb 21 2022 at 12:55):thoughts?
Anton (Feb 21 2022 at 13:18)::100: agree. Should we try to re-use that custom roc docs format for documenting the roc repo as well?
Jose Quesada (Feb 21 2022 at 13:51):Awesome, I can write up a proposal if everyone is ok with it. Not sure if there's a formal process defined for this sort of thing yet?
Jose Quesada (Feb 21 2022 at 13:52):What about in the context of documenting the Roc project itself?
Richard Feldman (Feb 21 2022 at 15:20):I'd say feel free to write it up in any format (e.g. gist is fine) and link it in this thread so we cna discuss!
Richard Feldman (Feb 21 2022 at 15:20):I think it's a reasonable idea to use it to document the Roc code base as well as user-facing-stuff :thumbs_up:
Last updated: Jun 16 2026 at 16:19 UTC