# Write documentation PRs not blog posts

**URL:** <https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942>\
**Category:** Teaching & Outreach\
**Tags:** discussion\
**Created:** [June 28, 2023, 6:32pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942 "2023-06-28T18:32:11Z")\
**Posts on this page:** 17\
**Page:** 2

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [June 30, 2023, 6:23pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/21 "2023-06-30T18:23:44Z")

</div>

You can access all the documentation from the manual or registered packages via [JuliaHub.com](http://JuliaHub.com):

[https://juliahub.com/ui/Search?q=&type=docs](https://juliahub.com/ui/Search?q=&type=docs)

For on ramping newbies, we have Julia Academy:

> **[Homepage](https://juliaacademy.com/)**
>
> The definitive source for learning all things Julia, for free!

---

<div class="post-metadata">

**Author:** ![gdalle](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gdalle/32/224680_2.png) [@gdalle](https://discourse.julialang.org/u/gdalle)\
**Post date:** [June 30, 2023, 7:29pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/22 "2023-06-30T19:29:47Z")

</div>

> [@Datseris](#):
>
> If I’d present documentation improvements I would say “I had a lasting impact on the quality and accessibility of a software by directly improving its documentation (which is the starting point for most users). This way I also learned to work with the core dev team.” which for me personally is a stronger statement than “I have a clear knowledge of a software and I can share this knowledge with others that may come across my blog”.

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:

1. Short term: writing the content
2. 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?**

---

<div class="post-metadata">

**Author:** ![jacobusmmsmit](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobusmmsmit/32/217669_2.png) [@jacobusmmsmit](https://discourse.julialang.org/u/jacobusmmsmit)\
**Post date:** [June 30, 2023, 7:40pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/23 "2023-06-30T19:40:40Z")

</div>

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](https://www.youtube.com/watch?v=_3vJSBk0Bls) 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.

---

<div class="post-metadata">

**Author:** ![gdalle](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gdalle/32/224680_2.png) [@gdalle](https://discourse.julialang.org/u/gdalle)\
**Post date:** [June 30, 2023, 7:50pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/24 "2023-06-30T19:50:46Z")

</div>

> [@jacobusmmsmit](#):
>
> Blog posts are more fun to write

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.

> [@jacobusmmsmit](#):
>
> blogs generally fit more into the tutorial or explanation part of the documentation quadrant.

I think there is an important distinction to make between “documentation” (the website with the URL [https://docs.julialang.org/en/v1/](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](https://julialang.org/learning/) category. But since this might be hard to get approved, my initial proposal settled on the next best thing with the Julia [blog](https://julialang.org/blog/)._

---

<div class="post-metadata">

**Author:** ![adienes](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/adienes/32/37459_2.png) [@adienes](https://discourse.julialang.org/u/adienes)\
**Post date:** [June 30, 2023, 8:01pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/25 "2023-06-30T20:01:45Z")

</div>

> [@jacobusmmsmit](#):
>
> Documenter.jl’s shockingly poor search functionality.

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

---

<div class="post-metadata">

**Author:** ![ToucheSir](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/touchesir/32/14411_2.png) [@ToucheSir](https://discourse.julialang.org/u/ToucheSir)\
**Post date:** [June 30, 2023, 8:46pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/26 "2023-06-30T20:46:02Z")

</div>

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!

> [@Nathan\_Boyer](#):
>
> Maybe simplified GitHub navigation is the best thing to start documenting then.

Does anyone know what niceties other languages for Rust provide here that Julia does not?

> [@Datseris](#):
>
> I think it is a good idea to add the same timestamps in the examples of a documentation, if you could foresee that they may break in the future. I haven’t done it so far, but now that you mention it, I definitely should. Or perhaps I could use Documenter.jl/Literate.jl to put an automatic stamp of when the code was run last.

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.

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [June 30, 2023, 8:51pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/27 "2023-06-30T20:51:36Z")

</div>

> [@jacobusmmsmit](#):
>
> 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 […]

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)

---

<div class="post-metadata">

**Author:** ![ToucheSir](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/touchesir/32/14411_2.png) [@ToucheSir](https://discourse.julialang.org/u/ToucheSir)\
**Post date:** [June 30, 2023, 8:54pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/28 "2023-06-30T20:54:02Z")

</div>

> [@jacobusmmsmit](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![rikh](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rikh/32/204104_2.png) [@rikh](https://discourse.julialang.org/u/rikh)\
**Post date:** [July 6, 2023, 2:39pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/29 "2023-07-06T14:39:06Z")

</div>

How about making PRs which add links to personal blog posts?

---

<div class="post-metadata">

**Author:** ![jacobusmmsmit](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobusmmsmit/32/217669_2.png) [@jacobusmmsmit](https://discourse.julialang.org/u/jacobusmmsmit)\
**Post date:** [July 6, 2023, 4:46pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/30 "2023-07-06T16:46:42Z")

</div>

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\].

* * *

1. see the SEO industry

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [July 6, 2023, 5:11pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/31 "2023-07-06T17:11:00Z")

</div>

At the risk of completely throwing a bone to the wolves, Hillel Wayne recently wrote this interesting article about this topic:

> **[My Problem With the Four-Document Model](https://www.hillelwayne.com/post/problems-with-the-4doc-model/)**
>
> Two universal facts about user documentation:
> Documentation is really important. We are really bad at writing it. We don’t have good theories on what makes for useful documentation. That is except for the four document model, or Diátaxis.1 I’m glad...

---

<div class="post-metadata">

**Author:** ![Mason](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mason/32/2423_2.png) [@Mason](https://discourse.julialang.org/u/Mason)\
**Post date:** [July 6, 2023, 7:03pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/32 "2023-07-06T19:03:40Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![gdalle](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gdalle/32/224680_2.png) [@gdalle](https://discourse.julialang.org/u/gdalle)\
**Post date:** [July 6, 2023, 8:12pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/33 "2023-07-06T20:12:04Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [July 6, 2023, 8:44pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/34 "2023-07-06T20:44:38Z")

</div>

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!

---

<div class="post-metadata">

**Author:** ![kevbonham](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kevbonham/32/216165_2.png) [@kevbonham](https://discourse.julialang.org/u/kevbonham)\
**Post date:** [July 11, 2023, 3:12am UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/35 "2023-07-11T03:12:20Z")

</div>

> [@Sukera](#):
>
> Hillel Wayne recently wrote this interesting article about this topic

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.

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [July 14, 2023, 11:17am UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/36 "2023-07-14T11:17:15Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dlakelan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dlakelan/32/8491_2.png) [@dlakelan](https://discourse.julialang.org/u/dlakelan)\
**Post date:** [July 30, 2023, 3:03am UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/37 "2023-07-30T03:03:52Z")

</div>

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

[Previous page](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942.md?page=1)