Skip to content
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

Adding "examples" section for real-life usages #1953

Closed
nickaein opened this issue Feb 22, 2020 · 5 comments
Closed

Adding "examples" section for real-life usages #1953

nickaein opened this issue Feb 22, 2020 · 5 comments
Labels
kind: enhancement/improvement state: stale the issue has not been updated in a while and will be closed automatically soon unless it is updated

Comments

@nickaein
Copy link
Contributor

Currently README provides a minimal set of examples about how the library can be used. While It covers most of basic functionality, some users occasionally have trouble in using the library in more complex situations. Here are some recent examples: #1930, #1874, #1892, #1931.

A user can eventually figure it out by reading the documentation, but having some examples for various use-cases which are closer to real-life scenarios can be very helpful in using the library "correctly" and can also reduce the number of opened issues related to usage problems.

Any thoughts or suggestions on adding such section to the library?

@nickaein nickaein changed the title Adding "examples" section Adding "examples" section for more real-life usages Feb 22, 2020
@nickaein nickaein changed the title Adding "examples" section for more real-life usages Adding "examples" section for real-life usages Feb 22, 2020
@nlohmann
Copy link
Owner

Good point. There is already an example for each function in the Doxygen documentation. I am a bit worried that adding another source of documentation may be confusing.

@dota17
Copy link
Contributor

dota17 commented Feb 24, 2020

I think we can add these source into github wiki.
In wiki, we can tell that the examples of complex situations and how to build or tips.

@nlohmann
Copy link
Owner

The Wiki is intentionally switched off for this project as it would be another source of information which could be even more confusing.

@nickaein
Copy link
Contributor Author

nickaein commented Mar 10, 2020

Whoops. I totally missed docs/examples directory. So this is where all example codes for the documentation is located.

Regarding the examples, I think there are two points to consider:

  1. My hunch is that users usually look for examples directory in root of a project and if they don't find one, they probably assume the project doesn't provide examples. It would be nice if we can find a workaround it. One option is to add an examples directory as a symbolic link to docs/examples. git supports symbolic links, but I'm not sure if it is portable.

  2. The current examples are tailored for the documentation of a specific feature. I believe having examples for more complex use-cases can be helpful too, to demonstrate how multiple features can be used in mix. These examples can be placed inside docs/examples too, while adding a "Samples" section in the documentation to reference them.

@stale
Copy link

stale bot commented Apr 13, 2020

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@stale stale bot added the state: stale the issue has not been updated in a while and will be closed automatically soon unless it is updated label Apr 13, 2020
@stale stale bot closed this as completed Apr 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: enhancement/improvement state: stale the issue has not been updated in a while and will be closed automatically soon unless it is updated
Projects
None yet
Development

No branches or pull requests

3 participants