Pretty Website

[mikeal]

I think we need a fancy website :)

I ran a poll today to see which http clients people use and people sent me a ton of clients I didn't know about, all of them promise based. I think a website that showed people docs for request-promise as well as request would be great, and also something that showed people the defaults API first, that saves so much time and almost nobody knows about it.

@request/promises

[simov]

👍 for fancy web sites, too bad I'm not a designer

@mikeal we should have at least a link to request-promise in the opening paragraph of the readme.

[analog-nico]

+1

In the Request-Promise README we recently added a cheat sheet that explains the usage based on use cases. Since we added that people started asking for additional use cases - which is a good sign. I think this could be a good approach for the website, too.

Indeed, .defaults(...) is something often unknown. Also, the website should dive into the whole streaming aspect. Again basing this on use cases would help newbies a lot.

IMHO a static site hosted on github.io into which we could feed markdown would be best. With markdown the community could easily contribute. I heard good things about Jekyll but never used it before.

I definitely can contribute a lot of the content but I am not sure if I have the time to work on the website design.

[tyabonil]

+1 for Github pages. GHP also has a few templates to choose from. We would need to maintain a gh-pages branch (or it looks like we can also set up a separate repo for the pages under the org).

[simov]

The repository can be anywhere and a third party domain name can be mapped to it as well. I like the cheat sheet approach, having good examples is always helpful, but that's not substitute for concise and clear documentation of the API. It's just that people have different ways of thinking and learning.

Also markdown is the way to go I agree, I just used the GitHub API to render my markdown files before pushing them to gh-pages in the past, but something well established would be better.

Also @analog-nico @tyabonil note that we're discussing a major rewrite of the module here. It shouldn't be a problem to promisify that as well.

[jabrena]

Reveal.js is very easy.

[analog-nico]

Thanks @simov for the pointer. We will gladly update Request-Promise.

[analog-nico]

I would suggest the overall structure of the website:

1. Home
   • Quick examples so the user can choose which approach to take:
     • Request with callbacks
     • Request-Promise with promises
     • Request with streams
2. Use Cases similar to those in the Request-Promise cheat sheet
   • Common use cases with callback-based and promise-based code maybe side by side
   • Streaming use cases
3. Documentation
   • Full API documentation in the style of the current Request README
4. Support / Contribute
   • Link to Gitter chat
   • Link to repos, contribution guidelines
   • Link to Request architecture docs etc.

Thoughts?

[jabrena]

It is a good starting point. I would add a section to interact with form-data and a section about upload files forma example.

[simov]

The overall structure is good.

@jabrena that should be part of the examples section I think, and we already have one form-data example - that particular use case is a bit odd, that's why I shared it, but many more examples can be added.

[simov]

@analog-nico you are now part of the Website team :)

The website is available at http://request.github.io until we have some better domain name, @mikeal

@analog-nico I also migrated the Promise team to the new teams, so let me know if something isn't working as expected.

@request/contributors if anyone want's to join @request/website ping me :)

[jabrena]

@simov Hi Simov, I would like to collaborate with the team.

[simov]

@jabrena invitation sent.

[tyabonil]

@simov I'd like to help, as well

[simov]

@tyabonil you are in, as you are already a member. BTW anyone can contribute because all repositories in the request organization are public.

[jabrena]

Hi mates,

If the site is going to have more than 10 documents, maybe we could adopt Jekyll

1. Home
1.1. Quick examples so the user can choose which approach to take:
1.1.1. Request with callbacks
1.1.2. Request-Promise with promises
1.1.3. Request with streams
2. Use Cases similar to those in the Request-Promise cheat sheet
2.1. Common use cases with callback-based and promise-based code maybe side by side
2.2. Streaming use cases
3. Documentation
3.1 Full API documentation in the style of the current Request README
4. Support / Contribute
4.1. Link to Gitter chat
4.2. Link to repos, contribution guidelines
4.3. Link to Request architecture docs etc.

Besides, we could add JSDoc for the whole library:
https://github.com/request/request/tree/master/lib
https://github.com/request/request-promise/tree/master/lib

To generate the API with a Gruntfile.
Example: https://github.com/prosociallearnEU/cf-nodejs-client/blob/master/Gruntfile.js

Any comment?

[simov]

Jekyll: looks promising, but if we find something similar written in Javascript it would be even better.

JSDoc: Personally not a big fan of a overly verbose comments in code. Have used it before and in the end it turned out to be just an annoyance, so I removed it from all of my projects.

The site will have lots of documents that's for sure, the most important thing is the structure, that will allow proper separation of all topics into small manageable markdown files.

[jabrena]

Hi @simov, JSDoc is pretty similar to Javadoc, we only have to add some Javascript comments in the the header of a prototype method or a function. I add an example:

    /**
     * Method to authenticate with Cloud Foundry UAA
     * @param  {String} username     [username]
     * @param  {String} password [password]
     * @return {JSon}          [UAA Response]
     */

Once, we have the code with the comments, we could generate the whole API with a command:

grunt docs

An example:
https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/

I think that Jekyll is pretty easy to maintain. We only have to put the documents in a folder and Jekyll integrate the template and other stuff. Frankly, I don't know a Client JS to generate a site. It is a nice approach. We could work in 2 parts: Look & Feel (Templating) & Contents to cover the 4 points.

[simov]

I know what JSDoc is, it's not a good fit for our use case. Unfortunately even the 'modules' inside the lib folder are not that easy to explain with comments, because often they modify state without returning anything, and accept objects that are simply huge, even if you document that method it won't help you much. That's why it's better to just read the code. Also these comments needs maintaining and in the end they will be just hanging there bloating our code base even more without bringing us anything useful.

It's better to have Javascript alternative to Jekyll becase:

• we may need to support it (read fixing bugs, adding features in that tool)
• our contributors will most likely have node installed instead of ruby

[lalitkapoor]

I've started to see more and more git books recently. here's an example: http://rackt.org/redux/

I could envision different sections for things like auth, cookies, etc.

[simov]

@lalitkapoor that's looking great actually 😲

[jabrena]

Yes the idea from @lalitkapoor is interesting.

Another alternative could be explore the Static Site generators based on Node.js.
http://www.sitepoint.com/6-nodejs-static-site-generators/
https://www.staticgen.com/

Hexo, could be a good candidate.
It seems easy to begin a site: https://hexo.io/docs/setup.html

[simov]

Nice! I like where this is going. I'm currently testing with GitBook and I'm very impressed, it's basically GitHub for books/documentations. I'm going to migrate one of my relatively big documentation (already markdown) websites there to see how it goes. I'll probably test with the rest of the solutions as well 👍

[simov]

Just for example it takes 30 seconds to build this, which is around the time needed to render these markdown files using the GitHub API.

So that's a very good result. Here is how the SUMMARY.md looks like:

# Summary

* [Install](markdown/install.md)
* Configuration
  * [config.json](markdown/config.md)
  * [settings.json](markdown/settings.md)
  * [custom.json](markdown/custom.md)
...

And the actual docs are standard GitHub Flavored Markdown, nothing fancy. And it took me under an hour to figure out everything and deploy it.

[simov]

So it seems that all of the solutions here are more like tools, where GitBook is like a platform. GitBook also have some tools around it, like editor, command line tool and so on, but they are not required. For example I just pushed a bunch of markdown files using git. So the learning curve is practically non existent - you just need to know markdown and git, which I think everyone knows.

My thinking is that we can at least try with GitBook because it's the most simple and quick solution. Even if we decide at some point that the GitBook docs are not fancy enough, we can always switch to another tool, because our files will be just flat markdown without any configuration around them.

Also this will lower the barrier for contributing.

[lalitkapoor]

👍

[mikeal]

-1 on JSDoc and Jekyll.

This is another option. https://readme.io/

[analog-nico]

+1 for platforms like GitBook and readme.io because they let us focus more on the content and less on the technology

I preferred readme.io because it is designed for our purposes (readme.io = library docs vs. a book). However, I signed up and found out it is basically a CMS which requires to edit the contents in their own editor. All is designed very well and is easy to use but we won't have markdown files which we host on GitHub. I think this is crucial to allow the community to contribute. Thus I prefer GitBook.

Nonetheless I pinged the readme.io support about markdown file support and will let you know what they say.

[simov]

@analog-nico I agree, plus using Git and GitHub gives you much more control.

Also it turned out that GitBook supports plugins. For example you can create book.json file and push it:

{
  "plugins" : [ "anchors" ]
}

This will add the Gitbook Anchors Plugin which currently have a bug in its styles, but my point is that we can even add some plugins or easily create our own if needed.

[simov]

I just pushed the initial structure of the docs here: https://request.gitbooks.io/request/content/
The repository is available at: https://github.com/request/request.github.io (push there)

The current directory structure is as follows:

├── book.json
├── docs
│   ├── api
│   │   └── index.md
│   ├── features
│   │   ├── auth.md
│   │   ├── cookies.md
│   │   └── index.md
│   └── promises
│       └── index.md
├── images
│   └── tms.gif
├── README.md
└── SUMMARY.md

Everything in the docs folder is markdown. I also added images folder in case we need those memes 😆

There is a Request organization on GitBook as well: https://www.gitbook.com/@request
No idea what's the point but I can add you there if you have account on GitBook.

@mikeal we need some good domain name ❕

Also everyone, take a look at how I'm adding named links to the markdown documents, this syntax helps with keeping the document clean and at the same time finding links easily.

Let me know if I'm missing something.

[lalitkapoor]

We could probably get request.js.org via https://dns.js.org

[simov]

👍 PR here js-org/js.org#519

[indus]

I would appreciate to register request.js.org for you.

I have already added your requested domain to JS.ORGs zonefile. But this way we stick to the urgly redirect/forwarding. As you mentioned GitBook also allows the CNAME thing similar to GitHub Pages. Have a look at the part On GitBook.com. I´m not familiar with GitBook but it sounds easy. So we should try this if GitHub Pages is really not an option for you...
The problem is that I already rejected other requests for the very same reason (redirect = "no content") and I want to keep it fair. But I keep the PR open until you find your prefered host and things sort out...

[indus]

After reading this thread from the beginning and the host/technology discussion in particular let me speak a word for GitHub Pages. What I like about it is not Jekyll or its usability; But the fact that it allows collaborative work (the reason why we all like GitHub for our code) gives some benefits for pages, too. Everybody can contribute via PRs (e.g. for typos), if you want to discuss on anything related to the page you have the issue section (this disscusion isn´t taking place on GitBooks) and you can use releases to keep "outdated" versions of the docs. I´m not sure if GitBook is providing the same...
Jekyll is more or less optional and your MD files with some CSS should render the same everywhere. But that's just my two cents.

[simov]

Thanks @indus, the code is still on GitHub when using GitBook (there is an option to push it directly to GitBook too). We are currently using a build hook that is triggered each time we push something in https://github.com/request/request.github.io

[indus]

Ah ok - good to know. I merged (and slightly modified) your PR

[simov]

Welcome request.js.org

🎉

[lalitkapoor]

👏 thanks @indus @simov :)

[analog-nico]

@simov Nice work! Give me till the weekend and I will join in and contribute a bunch of content.

[simov]

@analog-nico 👍 feel free to remove the silly gif, @lalitkapoor you have write access too

[nmaxcom]

What about a better docset? More examples or just behaviour explanation on authentication, cookies, redirects... The easy requests don't need explanation; the difficult ones have none or just a weak one.

[jabrena]

Good afternoon,

some weeks ago, we spoke about the website with some structure:

1. Home
1.1. Quick examples so the user can choose which approach to take:
1.1.1. Request with callbacks
1.1.2. Request-Promise with promises
1.1.3. Request with streams
2. Use Cases similar to those in the Request-Promise cheat sheet
2.1. Common use cases with callback-based and promise-based code maybe side by side
2.2. Streaming use cases
3. Documentation
3.1 Full API documentation in the style of the current Request README
4. Support / Contribute
4.1. Link to Gitter chat
4.2. Link to repos, contribution guidelines
4.3. Link to Request architecture docs etc.

I have some hours per week so I could do some pull request to the repo:
https://github.com/request/request.github.io

@simov @mikeal In you opinion, what is the next step in the website? I could like to collaborate with this documentation.

If you like, we could create some issues here:
https://github.com/request/request.github.io/issues

Cheers

Juan Antonio

[analog-nico]

Hi @jabrena , I offered to write a good portion of the documentation but was crazily busy the past weeks. The next weeks as well because I will move to another city. But I will try to do my share rather sooner than later. Being a maintainer of Request-Promise I think it is best if I do the promise related parts. If you could contribute to the Request related parts that would be awesome!

[jabrena]

For me is a good way to organize the issues. Tomorrow I will create some issues on:
https://github.com/request/request.github.io/issues

If I have permissions, the part about Request-Promise will be assigned to you and the part about @request/request for me.

Cheers

[ghost]

This is a really late comment, and I don't know any of you (I just think this project is awesome), but I wanted to point out that the DjangoCMS/Aldryn hosting-thing just made their "Live Server" a free option. This was maybe three days ago. It's a fairly dummy-proof (from what I can tell so far) implementation of the django platform, which stores the site on a cloud and offers stuff like front-end editing. It also supports Bootstrap, so it's not a bad mobile-friendly, pretty-looking option for making a site that doesn't look like it was made with templates (but was totally made with templates).

The free option only gives you 512/mb of transfer data a month, so basically nothing, but it made the 1gb/month option drop to $10 a month. You'd still have to register a domain (and probably pay for a standard SSL certificate), but it's still a really cheap option that easily puts your site's quality on par with other startups out there, and it also seems like a great choice if you think you might need to scale things up over time (they have plugins that work seamlessly with mailing list services, and other stuff that comes with a third party's monthly fees that I don't really understand). To start off, you might even be able to get away with the free 512mb/month option, if you put your documentation on PDF's, stick them in Google Drive, and see if you can let Google's servers handle most of the data.

I swear that I don't work for them -- I haven't even made a site yet, and I got one of those "Hi, are you alive?" emails from them after letting an empty project sit over there for two months. I actually came across your project as part of a never-ending search for the source url for an iframe without using ten million lines of javascript parsing, like this project does (I almost threw up when I looked at the javascript file that came over the wire on dev tools, but it does work amazingly well -- it comes with with absolutely insane source url's that would make you think it'd be an error-filled mess, but I've yet to stump the thing, even on origin-blocked request headers, which is where they build url's with Twitter and Facebook tags in them, and somehow flawlessly link to a video file from CNN.com).

My aim is to get from an object on a site, to pasting it in iframe form, within two clicks (four, I suppose, if you include the right-click as well). I figure it'd be a useless project if bloggers with iframe buttons were required to mess with dev tools, or even think about the network's existence at all. Your project looks like it might actually be the missing link I've been looking for -- I'll be sure to share the code if it works out! And, speaking of iframes, they wouldn't be a horrible idea for opening a portal to github documentation, so you could have it on your own site without actually hosting it. I think it's kind of like stealing your neighbor's electricity, except your neighbor still gets page views and ad revenue, so it's a win for all. If you went SUPER minimal with your site, you could actually do it with a half gig a month, and the more minimal your site is, the more mysterious/freshly discovered it makes your project look to visitors.

Um, I apologize for writing a novella in your thread -- word count got away from me a bit.

[stale]

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.

[reconbot]

Request is now in maintenance mode and wont be merging any new features. This website falls under that guideline. Please see #3142 for more information.