Improve Documentation

[capocasa]

This issue exists to develop an action plan to improve Nim's documentation, as initially discussed on the forum.

As roughly estimated by me (Carlo) there seems to be broad agreement that Nim's core documentation is very good but could use more examples and discuss details in an explicit way that are currently implied or glossed over.

Community projects seem to frequently be completely lacking in documentation, or the documentation is ineffective in that it doesn't cover the information required to understand what a project is for, when it should be used, how to get started, and how to master it. Occasionally, examples don't work or installation instructions fail.

This issue exists as an overview for documentation discussion and to hold a list of sub-tasks that were partially suggested by me and rather many on request in the forum discussion.

Note I've kind of stepped up into a kind of "documentation instigator" role because I saw the need, but in case someone thinks they can do it better, that's fine for me too! Help is always welcome too, of course.

I will be attaching tasks from the forum discussion to this one in the next days! Input always welcome.

[capocasa]

To an admin: Might I possibly get assigned the github privileges required to assign this task to myself, and assign sub-tasks to it? Thanks!!!!

[capocasa]

@ringabout Thanks for assigning me! Might I possibly receive the privileges required to assign sub-tasks? I'll only use them here on this task or after I've made sure everyone's ok with a change. "Triage" rights might work.

[Araq]

Fwiw I think "discoverability" is a bigger problem and I've some ideas how to improve it.

[ringabout]

@capocasa Invited! (Btw, you might discuss the documentation on the channel; someone on the channel might help)

[capocasa]

@Araq I'm all for discoverability, but by the way you phrased it, you seems to imply that documentation is by comparison unimportant- which amounts to active pushback against better documentation. Are you sure this is what you want?

[Araq]

you seems to imply that documentation is by comparison unimportant- which amounts to active pushback against better documentation. Are you sure this is what you want?

No. There will be no pushpack from my side.

[capocasa]

@Araq Great, thanks for clearing that up! I was unsure whether it was just a figure of speech or reflected an opinion.

Please feel free to share your ideas for improving discoverability, if you like, the subject does overlap- in a way documentation is about discoverability of features and techniques. I'm interested in helping with that as well- I have been evangelizing to "targets of opportunity" on Twitter and reddit but I don't have any kind of grand strategy about it.

[Araq]

For now I have:

• Cleanup the website's documentation page.
• Make the atlas tool opinionated in what packages it suggests. It should have a list of recommended packages and highlight these differently.

[PhilippMDoerner]

One solid starting point can also be Looking through the docs for "Deprecated" mentions and double checking whether the corresponding docs mention what the replacement is.
Decent example would be std/times doing this in multiple places:

https://nim-lang.org/docs/times.html#second%3D%2CDateTime%2CSecondRange

[juancarlospaco]

I been thinking that the Deprecated without message should be Deprecated,
so you must use a message to provide more information and a replacement.

[capocasa]

Here's a fairly low-hanging-fruit- go through the forum for good questions with really useful answers and put them into a how-to wiki. Then ask forum-users to add their future solutions to the wiki, perhaps with a Sticky thread.

I noticed how every time I need to do something specialist and niche in Nim I go to the forum and feel like I'm using an ugly hack, but if I need to do something speicalized and niche in Arch Linux I find a recipe on their wiki-style documentation site and feel like I'm doing things the canonical way. I also add stuff there a lot because it's easier than taking track of my notes.

That would also take a lot of pressure off the core docs to cover every conceivable use case that we users dream up.

I suppose such a wiki would have to be written in Nim, use RST as its native format, and cover the most important wiki features (versioning, undo and meta-comments). We could also use github wiki but that's a tiny bit too platform-dependant for my personal taste.

[ringabout]

There is an abandoned wiki repo https://github.com/nim-lang/wiki, which might be a good starting place.

[capocasa]

@ringabout Holy smokes that's fantastic, I had no idea this existed. Thanks!!! This is exactly the sort of information I think Nim needs most. A bunch of guides that cover getting stuff done with Nim more than Nim itself.

I wonder if it would make sense to have a Nim wiki software that uses git revisions and just resurrect the repo. I'm also reasonably good at hosting services and not losing data as well, not sure there... but I think the content would in any case make a fantastic starting point.