One of the recent Slack threads was pointing out how other languages such as Clojure and PHP have nice indices with user comments. I am wondering if we could co-opt Discourse for this this purpose.
To avoid crowding out other sections, I suggest a documentation section on Discourse.
My current prototype for this starts with trying to crowd source friendly string documentation for Julia:
A section is something? Or do you mean new Category ? I can only see Categories and Tags for organization in discourse. Currently a wiki topic is just a topic like all others, but can be edited by others. A wiki section/category needs a home page or index page for structure… just thinking… first things first, it’s nice idea and lowers the barriers.
I think a Category is what I am looking for.
Specifically, an overall category for Documentation would be good. A sub-category specifically for Base and Standard Library documentation would also be useful.
Yes, this. Who can do this? @mbauman ?
Some dedicated moderators could do the coordination and cleanups (like perhaps only wiki topics allowed, or tagging with “wiki” and these things). Also some kind of meta wiki pages (index, main, home, …) could be done by them. To keep it usefull !
But, I feel a bit lonely here, only me and you discussing. Perhaps you/we should first check if this is really wanted? Or we just start and we see if it gets some momentum?
Yes, it’s quite easy to create new categories — just one button click — but it’s harder to fill, populate, and maintain the topics within them. I’m not terribly convinced about documentation here. In my mind discourse is for discussions, and I’d really want these efforts focused on the docs.julialang.org manual itself.
I support the idea of a documentation category. I think the proposed category is broader than just Julia language documentation. It would also support questions about documentation for user-developed packages. Some of the topics would likely include questions about Documenter, DemoCards, DocumenterCitations, Quarto, book publishing, Literate, using Github Actions with Documenter, etc. etc.
I think the original question was a Category for documentation, not about documentation. That is, @mkitti wanted to use the Discourse to solicit/draft new documentation.
But as this thread shows, that category will be immediately misunderstood to be for questions about Documenter.jl, etc. – which would be an okay category to have, IMO.
As far as “calls for documentation” go, I’d be inclined to agree with @mbauman: better to do this as part of the development cycle (Github issues for docs.julialang.org etc, maybe even a Github wiki), which can always be augmented by a post in General Usage or Announcements or some other category to solicit community feedback.
We could create a Documentation section under tooling Tooling - Julia Programming Language
But I agree with Matt, it should be for questions and discussion about the tools themselves and not documentation for packages
I think we need both a category to discuss tooling for documentation, but also a place here on Discourse for documentation itself.
Yes, we should feed these efforts back into Github, but I think we should also acknowledge that a Github based process is not for everyone and also does not permit the same kind of discussion that can be had here.
Part of the Slack discussion is that other languages have user commentary adjacent to their official documentation. We could create a bespoke system for this, but I think it would be useful to have both the canonical well vetted documentation as well as user documentation.
I’m all for user-editable documentation, but shoehorning it into this Discourse seems like it would lead to a lot of confusion. Or, at least, I don’t know what exact workflow you envision or how you would communicate that workflow to the people you want to contribute to documentation.
Wouldn’t it be better to set up a project wiki or some other collaborative documentation writing platform specific to a given project? Again, Github has both a Wiki and a Discussion feature, but I’m sure there’s other Wiki+Comments platforms one could set up at, e.g., docswiki.julialang.org for user-contributed Julia documentation or drafting.
Is it really helpful to have a 16 year old note that the docs are misleading? Why not just fix the docs?
Not everyone has the time, patience, or skill to fix the docs, use git, and use Github.
Let’s stop assuming that everyone who is using Julia is a full fledged open source developer. Let’s make it easier for as many people as possible to help annotate and discuss specific Julia functions.
Let’s make it easier for both users and developers to find these discussions about specific functions so that we can evetually fix it.
Right, so these discussions belong to the docs website of a project and not offloaded onto discourse were people won’t find them.
On my personal website I use https://utteranc.es/ and I could see value in integrating that into Documenter.jl as an example this is used by https://haxe.org/manual/std.html
Sure. Instead of embedding a Github issue, why not embed a Discourse thread?
JSON is enabled on this site. For example here is the JSON of this thread.
Because the owner of the Package could self moderate GitHub and not depend on us existing/working?
