Is it my idea or many libraries assume a huge amount of pre-knowledge in their documentation. For what I have seen until now, many libraries that are wrappers or reimplementation of other libraries in other languages the documentation goes a little bit like this: “It works exactly the same as in l…

A documentation style guide is a good idea I think. A simple set of ground rules to follow. Not everyone (myself included) really knows how to write good documentation. That link @tim.holy posted is great.

One way to get better documented packages is to get the package author(s) to write JOSS article ( Submitting a paper to JOSS — JOSS documentation ). User documentation is in the JOSS requirements and they have some KPIs to check against. I don’t know if this is any easier task, but JOSS article may …

[image] Tero_Frondelius: User documentation is in the JOSS requirements and they have some KPIs to check against. I am not sure I understand how this would help get better documentation. Instead of writing docs because JOSS requires it, one might as well just write docs and be done with it. I…

In addition to Documenter.jl, Literate.jl is a amazing tool to expand your tests to working examples in the Documentation.

After more digging and investigating, I would have say that the Julia documentation is lacking in complete definitions and examples. Specifically, I tripped across a statement in the split function that read “if r != 0:-1 …”. I have spent about 3 hours trying to find a reference that explains the …

While this discussion is still fresh in our minds I’d like to turn it into something productive. There are a lot of good ideas but I think most would agree an additional style guide would be helpful (perhaps not personally but at least for people new to documenting code.) Should this be a new style…

[image] OliverEvans96: I think the fact that it’s all hosted in one place and easy to upload is helpful. We’ll soon have something systematic for this at https://juliahub.com (in beta) [image] Zach_Christensen: I think most would agree an additional style guide would be helpful (perhaps …

[image] c42f: the average open source developer is strongly incentivized to write the software so they can use it. However, there’s no such incentive for documentation. I am not sure I fully agree with this. I don’t have hard data to talk about the average FOSS developer, but in scientific co…

My comment about “no such incentive” was meant to be fairly restrictive: I mean to say there is no direct incentive for writing tutorials or how-tos because the core developers are not the audience for these things. Docs which help users to become contributors (or help developers with their old proj…

[image] c42f: Mature projects need to value their new users and provide useful documentation I would suggest that most, if not all, mature packages in Julia have some documentation. Some of them have very extensive docs, complete with tutorials and examples. Even a lot of packages with pre-1…

Non-friendly documentation

New to Julia

Topic		Replies	Views
Blog post about my experiences with Julia Community	259	17165	June 19, 2022
Write documentation PRs not blog posts Teaching & Outreach discussion	36	3074	July 30, 2023
(Not-So-)Crazy idea: Make the julia docs a Pluto notebook Community documentation , pluto	41	5213	September 30, 2021
Coordinating community efforts to enrich function docs General Usage	44	2131	May 2, 2022
Julia among the most loved languages Community	31	3620	June 11, 2020

Non-friendly documentation

Related topics