You can access all the documentation from the manual or registered packages via JuliaHub.com:
https://juliahub.com/ui/Search?q=&type=docs
For on ramping newbies, we have Julia Academy:
1 Like
You make a strong case @Datseris, and you did convince me. From now on, my end goal will be to add this to the official documentation.
However, I think there are two separate challenges to distinguish here:
- Short term: writing the content
- Medium term: sharing the content
Designing a blog post is not necessarily the ultimate answer for 2, only the motivation I found for 1. Beyond the name recognition (which I agree is pretty shallow), there is also the feeling of seeing the results of your efforts in real time. Itâs very pleasant to be able to write a few lines, commit and then see the website a few minutes later.
If I set out to contribute it all to the official docs from the start, this would translate into 20 issues and as many PRs open on different pages, with review delays anywhere between a week and a year. Knowing myself, I would probably lose interest after a while, and far less would get done in the short term.
I donât know how other people think, but I believe this instant reward and quick iteration ability is among the main drivers of the ecosystem fragmentation. Except in this case it may not be so detrimental. After all, duplicating docs only makes it easier to find. And the task of copy-pasting and adapting an existing blog into the docs is much less daunting than writing it all from scratch.
To sum up, I propose to keep drafting the posts in a separate repo, so that they can take shape quickly. Then I would like to add them to the Julia blog, to make them easily discoverable in the short term. And in the medium term, I could coordinate efforts to transfer them to the docs, but importantly they would already be available to guide beginners in the meantime. How does that sound?
8 Likes
I want to push back slightly on âdocs over blogsâ.
Blog posts are more fun to write due to creative agency. I donât have to worry about fitting the formal style of the docs and I can put memes or personal anecdotes that make the post more engaging but would never be allowed in docs. Blog posts also are more fun to read partly because of this, and partly because blogs generally fit more into the tutorial or explanation part of the documentation quadrant.
The Julia docs are dense. This is off putting to newbies (heck, even to me). There are wizards who know the docs really well and know every subsection of every but most people are not wizards and do not read docs for fun. Heck, the whole reason I made my workflow/latency video was because my friend (who is absolutely no slouch at scientific programming) was frustrated that he had to try so hard to find the exact information that was relevant to him. Admittedly, this is partly a problem with Documenter.jlâs shockingly poor search functionality.
Docs should be information dense, all of the information should be there. But docs are most helpful when you only have known unknowns. Most often, however, Iâm trying to do something that involves unknown unknowns and I want to be able to search for the general thing Iâm trying to do, not a specific, technical detail about something I know I donât understand.
A master at a topic can get by without tutorials when trying something related but new, a newbie doing the same thing requires explanations and step-by-step guides on what to do. When I use MATLAB, I just use it and run to the docs for help, Iâve never even looked at a tutorial; when I first used Rust, however, I read the whole book as well as watched several videos before I even knew where to begin.
Blogs, videos, and related content provide context that does not belong in docs-style documentation.
8 Likes
Thatâs what I was trying to convey: even if the content makes its way to the docs in the end, the mere fact that it starts out as a blog will help us get it done more quickly.
I think there is an important distinction to make between âdocumentationâ (the website with the URL https://docs.julialang.org/en/v1/) and âdocumentationâ (the content of said website). Nothing is stopping us from putting stuff from a different Divio quadrant on the documentation website, or even on the official Julia website.*
Only it hasnât really been done sofar, and might require a whole new section. In addition to âManualâ, there could be a âToolboxâ or âWorkflowsâ section before we get to the âBaseâ and âStandard Libraryâ? Again, thatâs a momentous change, and it would involve lots of friction, which is why I chose the easy way for now.
*Actually the Julia website is where I think the âModern Julia Workflowsâ truly belong, right up in the learning category. But since this might be hard to get approved, my initial proposal settled on the next best thing with the Julia blog.
6 Likes
So itâs not just me!
I thought I just had really bad âsearch prompt engineering.â I started cloning repos and searching *.md locally lol
5 Likes
This is the first time Iâve seen both of those mentioned in the same paragraph, which suggests there needs to be an on-ramp for the on-ramp!
Does anyone know what niceties other languages for Rust provide here that Julia does not?
As with many of the suggestions in this thread, I feel turnkey solutions (e.g. inclusion by default in Documenter.jl) are the only way to drive successful adoption. Custom solutions often bitrot because specific package contributors do not have the bandwidth to maintain bespoke tooling.
2 Likes
This is actually a solid argument. Indeed, some of this type of material should stay with the owner. I would argue that having a bit of both is probably best. Putting a large portion of such generated documentation-related or instruction-related material in the docs is clearly beneficial, but keeping some for your own blog also provides the freedom of expression that is rewarding in its own right.
(note that personally I wouldnât really care if a contributed example to one of the projects I maintain was of different tone. After all, open source is written and used by many different people, thatâs different styles of usage examples is a natural consequence. But of course I can also see how some developers would prefer the documentation to share a writing style, this also has its own advantages)
2 Likes
IME this is what kills the momentum of many docs PRs, and as a maintainer who is frequently guilty of requesting multiple rounds of revisions to grind down someoneâs hard work into a form which fits the existing docs Iâm at a loss for how to fix it.
My current thoughts are that official docs sites seem to be too inflexible for tutorials and those should primarily come from third parties. They take the longest to write and edit, yet bitrot the fastest. It may make more sense to focus on how-to guides instead. Explanations and Reference docs also often need some love, but those need better tooling support than we currently have IMO.
7 Likes
How about making PRs which add links to personal blog posts?
Idk, something feels a little wrong linking to personal blog posts in docs. That said, providing useful links to resources in alternative styles is good, especially since discoverability of such resources is a major problem[1].
see the SEO industry âŠď¸
At the risk of completely throwing a bone to the wolves, Hillel Wayne recently wrote this interesting article about this topic:
12 Likes
Sorry if this was already mentioned somewhere, but why not both? I.e. when you write a blogpost on something that you think the documentation doesnât cover well, it can make a lot of sense to write a docs PR in parallel to the blog post.
Style, target audience, structure and many other things are wildly different when you go from a blog post to a PR (or more likely to a dozen PRs).
Btw weâve talked it out with @jacobusmmsmit and @hill: âModern Julia Workflowsâ will remain a blog post project for the time being, so that we can get it off the ground more easily. Once it has found a safe and lasting home on the Julia blog, weâll try to pour some of its content into the docs.
4 Likes
That was a great read. Put a few ideas together for me that had been banging around, but I couldnât put my finger on. Thanks!
2 Likes
I like it, but I never read the 4 document model as being categorical - there primary figure has the things on continuous axes! Of course a tutorial might have some explanation, and have some how-to elements, etc.
I canât tell if itâs my training in biology or Buddhism, but I find peopleâs desire to discretize concepts that are clearly continuous just because theyâre given a label quite challenging.
4 Likes
If your watch Laingâs talk and/or read the description of the system, he is staunchly advocating that one not allow the 4 types to bleed into one another at all. The graphic looks like a continuum, but the axis are just describing the situations in which each type is useful. Laing seems to view these commonalities as a threat because they blur the lines of what a specific piece of documentation is trying to accomplish.
2 Likes
To me the one component of his four type scheme that has the least separation is the understanding oriented explanation. Itâs entirely plausible that you would need to use some sort of examples that might look like a tutorial in an understanding oriented document. you might need to pull out bits from the reference manual and quote it and then describe what is special about that stuff. you might need to give an example of how to do something like his how to document and then explain why you would do it that way and not do it some other way.
but you canât necessarily expect everyone to have gone and done tutorials and walk through the how to of that particular topic and so forth so I think that particular document needs to interact with all the other types