New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[help wanted] Better stdlib documentation #10330

Open
narimiran opened this Issue Jan 16, 2019 · 15 comments

Comments

Projects
None yet
8 participants
@narimiran
Copy link
Member

narimiran commented Jan 16, 2019

I've started working on improving the documentation of Nim standard library, but that is a big task for only one person, so now I'm asking for community help for some relatively small modules, where one could improve the documentation in their free time in a reasonable amount of time.

We now have the improved documentation for four most-used modules (strutils, sequtils, tables, math; see some before and after screenshots), and this can now be used as a guide/suggestion for you what the improved documentation consists of.
Basically: a short introduction with an example how to use the module and links to similar modules or modules which can be used in combination with the documented module; examples (using runnableExamples) of usages of procs and templates, with links to similar the procs/templates.

This is not complicated (you can use these already done modules to see how to do something, if necessary) and even newcomers to Nim can work on this task — if you need any help, write a comment below or ping me on IRC/Gitter.

When you make some changes, you can build .html locally with nim doc path/to/file to check if everything is rendered as it should.

Here is a list of modules which are in need for some love, in decreasing order of priority (based on the number of projects using them), but whichever of these you improve it is one step closer to our goal.
(If you don't have much time, I've marked the smallest modules which shouldn't take too long)

If some module is not on this list, that means it either already has an okayish documentation (to be improved later) or I plan to work on it (EDIT: or it is not used very often, based on this).
(If you really want, you can work on those too :))

You can find the current versions of documentation here, and most of the libraries (their .nim file) are located in lib/pure directory.

When you start working on one of these, write it in a comment below so there's no duplication of work.

Thank you in advance for your help!

@narimiran narimiran pinned this issue Jan 16, 2019

@narimiran narimiran added the Easy label Jan 16, 2019

@alehander42

This comment has been minimized.

Copy link
Member

alehander42 commented Jan 16, 2019

Is jsffi.nim with okayish doc, or is it in your todo list?

@narimiran

This comment has been minimized.

Copy link
Member Author

narimiran commented Jan 16, 2019

Is jsffi.nim with okayish doc, or is it in your todo list?

It is in the third, not mentioned category :) Not used very often (based on this).

But if you want to work on it — please do.

@alehander42

This comment has been minimized.

Copy link
Member

alehander42 commented Jan 16, 2019

this is a bit misleading, as it just means the JavaScript backend is not used so much in the github repos: which makes sense, as most of them are libs/tools, not applications, however it is almost always imported in jsbackend-based code: I'll try to improve the docs

@narimiran

This comment has been minimized.

Copy link
Member Author

narimiran commented Jan 16, 2019

this is a bit misleading

It is hard to find some cover-it-all metric, so I decided to take that list as a starting point (rather than dumping a much longer list of modules :D). I'm aware of its limitations.

however it is almost always imported in jsbackend-based code

I have no experience in JS, so if that's the case: jsffi is then quite high on our priority list.

I'll try to improve the docs

Thank you!

@alehander42

This comment has been minimized.

Copy link
Member

alehander42 commented Jan 16, 2019

Sorry, I agree with the metric, just wanted to explain why it gives a strange result in this case, cheers

@dom96

This comment has been minimized.

Copy link
Member

dom96 commented Jan 16, 2019

see some before and after screenshots

This is great, I've got some feedback though regarding the existing docs:

  • Many top-level examples are not testable, they use echo instead of doAssert. Please consider fixing this and enforcing it for any new documentation. Runnable examples are possible in top-level examples, right?

  • The "Author" almost always is "Nim Contributors". When this is not the case the actual author is the person who created the module in the first place, but they may not have contributed to it in a while. I think it's far more genuine and in respect of our contributors to change everything to "Nim Contributors" with a link to the history of that file on GitHub (or some other page that shows the contributors).

By the way, please emphasise to people that the top-level examples should ideally be short and sweet. I like to think that most people share my opinion on this: when I want to figure out how to do something I don't want to wade through a 50 line example. See the json docs for an example of what IMO is good docs: https://nim-lang.org/docs/json.html#overview (the "creating JSON" example could in fact be a bit more terse and better formatted)

@narimiran

This comment has been minimized.

Copy link
Member Author

narimiran commented Jan 16, 2019

Many top-level examples are not testable, they use echo instead of doAssert

...and they are part of .. code-block::, because I didn't like the looks of runnableExamples when used for top-level documentation (putting bold Examples: where that is not needed, some different-colored line to the left of the text following it).
That's why I decided to keep the existing echos (since code-block is not tested), and continue to write the top-level examples in that style.

The "Author" almost always is "Nim Contributors". When this is not the case the actual author is the person who created the module in the first place, but they may not have contributed to it in a while.

Can we just remove that field, since most of the existing documentation doesn't use it? (I introduced it because sequtils had it, but IMO it didn't reflect the reality, like you also noticed.)

please emphasise to people that the top-level examples should ideally be short and sweet

...while long enough to showcase a common usage of the module and its most-used functions. (I agree that JSON is a nice example)

@Araq

This comment has been minimized.

Copy link
Member

Araq commented Jan 16, 2019

...and they are part of .. code-block::, because I didn't like the looks of runnableExamples when used for top-level documentation (putting bold Examples: where that is not needed, some different-colored line to the left of the text following it).

We should change the styling instead. Examples that are not checked do bitrot.

@dom96

This comment has been minimized.

Copy link
Member

dom96 commented Jan 16, 2019

Can we just remove that field, since most of the existing documentation doesn't use it? (I introduced it because sequtils had it, but IMO it didn't reflect the reality, like you also noticed.)

Go for it.

@GordonBGood

This comment has been minimized.

Copy link

GordonBGood commented Jan 17, 2019

I'm not sure where this would go on your list, but there are some modules that are very useful but don't appear on the main Nim Standard Library page listing the available modules.

The one I've identified, is bitops, which is very useful when one wants to call through to the CPU built-in POPCNT and other low level instructions (when the architecture supports it). I found it only thanks to Google.

As I said, there may be more...

@Jjp137

This comment has been minimized.

Copy link
Contributor

Jjp137 commented Jan 19, 2019

I'm still learning Nim, but I like the language and I want to help. I'll work on improving the docs for parseopt since I have used it a little bit.

@jiro4989

This comment has been minimized.

Copy link
Contributor

jiro4989 commented Jan 20, 2019

I'm learning nim too. I'll try to work docs of parsecsv.

@MandeepSinghey

This comment has been minimized.

Copy link
Contributor

MandeepSinghey commented Jan 26, 2019

I am a new comer to NIM, happy to help.

Actually as I am starting to use NIM that is one of the limitations i see for a newbee.

Explained the proc "pretty" in detail, file: json.nim with comments and sample program #10466

@narimiran

This comment has been minimized.

Copy link
Member Author

narimiran commented Jan 27, 2019

@GordonBGood:

I'm not sure where this would go on your list, but there are some modules that are very useful but don't appear on the main Nim Standard Library page listing the available modules.

Done. See https://nim-lang.github.io/Nim/lib.html for the updated version.


@MandeepSinghey:

Explained the proc "pretty" in detail, file: json.nim with comments and sample program #10466

Before you start, take a look at the files for which @ThomasTJdev, @Jjp137 and @jiro4989 have written the improved documentation (thank you guys!!). There are links in the original post at the top, and that should help to get you started to see what and how to do. If you need any further help, feel free to contact me, either here or on IRC.

@Jjp137

This comment has been minimized.

Copy link
Contributor

Jjp137 commented Jan 29, 2019

I'd like to help some more, so I'll work on improving the docs for the random module.

@narimiran narimiran pinned this issue Feb 11, 2019

@narimiran narimiran unpinned this issue Feb 12, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment