# 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:** 1\
**Showing post:** 15

<div class="post-metadata">

**Author:** ![gdalle](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gdalle/32/27854_2.png) [@gdalle](https://discourse.julialang.org/u/gdalle)\
**Post date:** [June 30, 2023, 12:04pm UTC](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/15 "2023-06-30T12:04:44Z")

</div>

As one of the [persons behind ModernJuliaWorkflows](https://discourse.julialang.org/t/seeking-feedback-blog-post-about-modern-julia-workflows/100324), I can only agree with @Nathan_Boyer that the ideal format would be additional documentation.  
I will outline some of the reasons (more or less valid) that made me choose a blog post instead. Note that I am open to discussion and that nothing is set in stone yet.

## Scale

With this project, we’re simultaneously trying to hit a very narrow target (only workflow tools, no domain-specific advice) and a very broad one (all the workflow tools ever created). The corresponding content in the Julia documentation is scattered across many different pages: [getting started](https://docs.julialang.org/en/v1/manual/getting-started/), [documentation](https://docs.julialang.org/en/v1/manual/documentation/), [performance tips](https://docs.julialang.org/en/v1/manual/performance-tips/), [workflow tips](https://docs.julialang.org/en/v1/manual/workflow-tips/), [FAQ](https://docs.julialang.org/en/v1/manual/faq/) and a whole lot more. Updating all of this in a coherent and synchronous manner, without duplicates or contradiction, would result in a humongous PR, that no one would want to review, and it would take literal months.

Centralizing the content in a small blog allows a few writers (for now including @jacobusmmsmit, Adrian Hill and myself) to get it up and running much more easily, until we reach a coherent result. After that, **nothing would make me happier than seeing people turn the content of the blog into documentation pages** , perhaps in smaller chunks. Consider my permission granted to copy everything from there into the official docs (I’ll also add it to the blog front page).

## Modernity

The claim “Modern Julia Workflows” can only hold true for a limited period of time. New packages emerge monthly, and keeping such a list up-to-date is, again, a huge endeavor that I don’t want to commit to.  
Many parts in the Julia documentation are outdated but not marked as such. The upside of a blog post is that there is a timestamp: “this was the state of the art in the summer of 2023, but maybe things have changed since then”.

## Recognition

I spend lots of time contributing to the Julia ecosystem, and as most of us know, it’s a thankless job. Especially in academia, where open source development is not regarded as worthy of our time or effort. So I must admit, having my name on a blog post (instead of an obscure docs PR) was a sweet and motivating prospect. That is definitely a questionable motive, but 🤷

---

_[View the full topic](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942)._