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

Compile README.md w/ documentary #91

Closed
wants to merge 2 commits into from

Conversation

@zavr-1
Copy link

commented Sep 5, 2018

documentary is a documentation pre-processor which allows to embed examples and fork them to include the output in the README. It's much better than copying and pasting by hand, because it will also make visible when an example does not actually work, or hasn't been updated (e.g., the --remove option in the CLI in this PR).

I hope you like it and it'd be great if this package could be one of the first 3-rd party software which uses it!

@zavr-1 zavr-1 force-pushed the docume:master branch from 7be4259 to d1f6eaf Sep 5, 2018

@shellscape

This comment has been minimized.

Copy link
Collaborator

commented Sep 5, 2018

Thanks very much for putting the effort into your PR, and for the interest in csv-parser. Unfortunately we're going to have to pass on this - it just introduces too much complexity and tech debt (separate files, an additional dev dependency, script, build step) for too little benefit. While documentary looks like it's better suited towards projects with large READMEs, the README for csv-parser is pretty lean.

@shellscape shellscape closed this Sep 5, 2018

@zavr-1

This comment has been minimized.

Copy link
Author

commented Sep 5, 2018

OK thanks. The advantages are clear though:

  1. You'll be sure that examples are always working (e.g., the main example in the PR was not working correctly as there were spaces between commas -- it might confuse less experienced developers).
  2. This is the most important one -- there is so much saved time in copying and pasting examples programs.
  3. File splitting -- you don't have to always scroll for ages find the relevant part in the README file
  4. You get more quality control as well because when running the documentation scripts, there will be a problem if something isn't working right).
  5. Table of Contents makes navigation so much easier, and it also makes the documentation structure more available to grasp immediately.

I'm can't insist on you making use of it, but it's so handy I'm sure that 1 build script is worth it. There's 8 very small dependencies, whereas you've already got ava with babel which has thousands of deps. Sometimes I'm reluctant to try new stuff as well but then I give it a go and it turns out to be brilliant. up to u. cheers

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.