# Coordinating community efforts to enrich function docs

**URL:** <https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338>\
**Category:** General Usage\
**Created:** [May 1, 2022, 5:46pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338 "2022-05-01T17:46:58Z")\
**Posts on this page:** 20\
**Page:** 2

<div class="post-metadata">

**Author:** ![ImreSamu](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/imresamu/32/20677_2.png) [@ImreSamu](https://discourse.julialang.org/u/ImreSamu)\
**Post date:** [May 1, 2022, 9:05pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/22 "2022-05-01T21:05:53Z")

</div>

> [@johnmyleswhite](#):
>
> I would skip some of the suggested Wikipedia links for now. I think it’s setting the bar too high in a way that will stifle community work.

sorry and agree …

(in the future) I will try to create a prototype - by linking with Wikidata ( a simple macro? )

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 9:13pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/23 "2022-05-01T21:13:41Z")

</div>

I’ve created a PR to try to address your specific concerns. There is likely still to be more work to do afterwards.

[https://github.com/JuliaLang/julia/pull/45144](https://github.com/JuliaLang/julia/pull/45144)

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [May 1, 2022, 9:20pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/24 "2022-05-01T21:20:38Z")

</div>

Ah, I meant on your repo, just as an alternative to the CSV so folks don’t have to make PRs to that file to coordinate. Although since people can’t edit each other’s issues to e.g. add their name, maybe it’ll be messier than the CSV file.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 9:24pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/25 "2022-05-01T21:24:23Z")

</div>

The other option is to use a Google spreadsheet. That’s definitely easier for me, but I am not sure if others will complain. If I hear more positive voices, I’ll make that change.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [May 1, 2022, 9:37pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/26 "2022-05-01T21:37:55Z")

</div>

OK, so I gather this is a proposal to improve the reference manual?  
If so, good. But what about the overall structure of the documentation?  
If you think about the recent thread, most of the misconceptions and  
misperceptions can be tracked back to a confusion about where to go to get what.

I think it would be good to have a broad and not too shallow look at  
what the documentation should look like to someone new to the language, starting  
with the “Documentation” button.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 9:49pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/27 "2022-05-01T21:49:45Z")

</div>

Yes, this is a tactical attempt to make rapid, iterative progress on the documentation. I’m open to more strategic re-evaluations, but I’m not clear there’s someone ready to take on the task of writing a large body of fully new documents about Julia. If you’re up for it, I think it would be extremely well received.

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [May 1, 2022, 10:32pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/28 "2022-05-01T22:32:20Z")

</div>

@printf

I miss an example how to print into a string. Well, you can use an IO buffer, but how?

---

<div class="post-metadata">

**Author:** ![giordano](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/giordano/32/2166_2.png) [@giordano](https://discourse.julialang.org/u/giordano)\
**Post date:** [May 1, 2022, 11:25pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/29 "2022-05-01T23:25:41Z")

</div>

You have to use [`@sprintf`](https://docs.julialang.org/en/v1/stdlib/Printf/#Printf.@sprintf), whose docstring already shows such an example, here is another simple one:

```julia
julia> using Printf

julia> @sprintf "%08.5f" pi
"03.14159"

```

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [May 1, 2022, 11:51pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/30 "2022-05-01T23:51:04Z")

</div>

Agreed, a body of brand new documents is a big ask.  
I have given it some thought, and may be what may begin to address this  
is a good index. I will sketch something out.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 2, 2022, 12:22am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/31 "2022-05-02T00:22:53Z")

</div>

It is substantially less clear, but you do this in steps using `@printf`:

```julia
julia> using Printf

julia> io = IOBuffer();

julia> @printf(io, "%08.5f", pi)

julia> String(take!(io))
"03.14159"

```

This is very close to an example in the documentation for `take!`.

---

<div class="post-metadata">

**Author:** ![TheCedarPrince](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/thecedarprince/32/17323_2.png) [@TheCedarPrince](https://discourse.julialang.org/u/TheCedarPrince)\
**Post date:** [May 2, 2022, 1:04am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/32 "2022-05-02T01:04:01Z")

</div>

Hey John,

Quick question - how do I contribute to the repo you created?  
Thanks!

~ tcp 🌳

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 2, 2022, 1:28am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/33 "2022-05-02T01:28:36Z")

</div>

The repo is only meant to track project management for improving the docs. Contributions could include:

1. Editing the CSV file tracking functions that need doc changes.
2. Opening an issue to ask someone to change the CSV file.
3. Opening an issue to propose doc changes with just the text you’d like to see added, but need help getting someone to write a PR with you.

---

<div class="post-metadata">

**Author:** ![TheCedarPrince](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/thecedarprince/32/17323_2.png) [@TheCedarPrince](https://discourse.julialang.org/u/TheCedarPrince)\
**Post date:** [May 2, 2022, 2:40am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/34 "2022-05-02T02:40:34Z")

</div>

Ope - I totally missed the CSV link and the CSV in the repo after reading the README.  
Thanks!

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [May 2, 2022, 6:03am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/35 "2022-05-02T06:03:48Z")

</div>

> [@giordano](#):
>
> You have to use [`@sprintf`](https://docs.julialang.org/en/v1/stdlib/Printf/#Printf.@sprintf)

Well, but this is not mentioned in the docu of `@printf`…

So there should be a sentence added: “If you want to print into a string, use `@sprintf`” …

---

<div class="post-metadata">

**Author:** ![carstenbauer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/carstenbauer/32/4981_2.png) [@carstenbauer](https://discourse.julialang.org/u/carstenbauer)\
**Post date:** [May 2, 2022, 6:53am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/36 "2022-05-02T06:53:44Z")

</div>

Just a thought: you could try to form a workgroup / taskforce for this which, for example, could meet once a month. Maybe there are some folks willing to participate in this effort and just need a structured environment to do so.

---

<div class="post-metadata">

**Author:** ![wfrgra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/wfrgra/32/10702_2.png) [@wfrgra](https://discourse.julialang.org/u/wfrgra)\
**Post date:** [May 2, 2022, 6:55am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/37 "2022-05-02T06:55:49Z")

</div>

Would it be possible to get a modified version of the help prompt to strip away most of the text and just display all the examples in the docstrings? eg:  
`?e map` (e for example) →

```julia
julia> map(x -> x * 2, [1, 2, 3])
  3-element Vector{Int64}:
   2
   4
   6
  
  julia> map(+, [1, 2, 3], [10, 20, 30])
  3-element Vector{Int64}:
   11
   22
   33

```

or maybe just

```julia
map(x -> x * 2, [1, 2, 3])
map(+, [1, 2, 3], [10, 20, 30])

```

This would give us a quick version of [tldr](https://tldr.sh) to contrast with our existing man pages/docstrings and without needing to rewrite the documentation. It wouldn’t help newcomers much, but I would find seeing a quick example of syntax very handy when I know the function, but have forgotten keywords and syntax. It could go some way towards @PetrKryslUCSD idea of tiered levels of documentation too.  
In general I find it a bit hard to discover functions in Julia, and I think this could be improved somewhat by focusing on adding more functions to the “See also” sections of docstrings everywhere, as demonstrated above by @ufechner7 . Making those functions (and the ones listed by the help search) have clickable links to their help docstrings would be a massive UI improvement too

---

<div class="post-metadata">

**Author:** ![antoine-levitt](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/antoine-levitt/32/4008_2.png) [@antoine-levitt](https://discourse.julialang.org/u/antoine-levitt)\
**Post date:** [May 2, 2022, 7:06am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/38 "2022-05-02T07:06:50Z")

</div>

I opened a new thread to try and figure out how to get people to contribute more easily, would be great if people here could chime in there :

> [@Lowering the bar for beginner contributions](https://discourse.julialang.org/t/lowering-the-bar-for-beginner-contributions/80355):
>
> (opening a new thread to not distract from the effort in [https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/)) Looking over the recent discussion about improving docs, it’s clear that people find issues they could fix with the docs but don’t necessarily open issue/prs to fix them. Is there something we can do here? First, we should understand why people don’t contribute. Is it git panic? The github contribution model is certainly intimidating at first. The…

---

<div class="post-metadata">

**Author:** ![giordano](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/giordano/32/2166_2.png) [@giordano](https://discourse.julialang.org/u/giordano)\
**Post date:** [May 2, 2022, 7:27am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/39 "2022-05-02T07:27:42Z")

</div>

> [@ufechner7](#):
>
> Well, but this is not mentioned in the docu of `@printf` …

To be fair, the docstring of [`@printf`](https://docs.julialang.org/en/v1/stdlib/Printf/#Printf.@printf) _ **does** _ mention `@sprintf` (the entire documentation of the `Printf` module consists of these two macros only) and the name `sprintf`, like `printf`, comes from C where [this function](https://en.cppreference.com/w/c/io/sprintf) is used to print to a _ **s** _tring, so this is widely popular among programmers with experience in languages similar to C. That said, documentation shouldn’t assume prior experience in other languages, so adding a mention to the use case of printing a string is useful.

> [@ufechner7](#):
>
> So there should be a sentence added: "If you want to print into a string, use `@sprintf` " …

Mind opening a pull request? 🙂

---

<div class="post-metadata">

**Author:** ![Elmo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/elmo/32/17979_2.png) [@Elmo](https://discourse.julialang.org/u/Elmo)\
**Post date:** [May 2, 2022, 7:51am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/40 "2022-05-02T07:51:16Z")

</div>

I second this. I would be willing to contribute if given tasks to do. Unfortunately, I don’t have time right now to help with the hard part - making a sensible task list…

---

<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:** [May 2, 2022, 8:04am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/41 "2022-05-02T08:04:54Z")

</div>

> [@ufechner7](#):
>
> "If you want to print into a string, use `@sprintf` "

> [@giordano](#):
>
> Mind opening a pull request? 🙂

I started one here:

> <https://github.com/JuliaLang/julia/pull/45148>
>
> From:
> https://discourse.julialang.org/t/coordinating-community-efforts-to-enric…h-function-docs/80338/38
> 
> Alternative text:
> 
> \> If you want to print into a string, use @sprintf.

[Previous page](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338.md?page=1)

[Next page](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338.md?page=3)