Next.js: Suggested documentation improvements

[niksurff]

A quick brain dump of all the questions that arose while getting started with next.js. Some of these might be answered already and I just haven't looked hard enough.

How next.js improves performance

As I see it a major responsibility of the next.js build process and server is performance improvements.
Some are documented and some not and there doesn't seem to be a central place to look up all that is done.

I'd like to see a comprehensive list (possibly with reasoning and resources) of all the steps the build process and server takes inherently (e.g. compression, HTTP headers, minification, code splitting, etc.). And also steps it doesn't take (yet), pitfalls and configuration/extensions that the end user might have to implement by themselves. The Wiki might be a good place for such a list.

Configuration File

The README.md's custom configuration section seems incomplete in terms of describing what keys the exported object from next.config.js accepts. Based on present documentation there is only one key webpack. Is that all there is for the moment?

Programmatic API

A start to document next.js' programmatic API is taken in section Custom server and routing of README.md. What I'm missing is proper documentation for instance methods like getRequestHandler(), render() etc.

---

I'm more than happy to help with improvements but would like some suggestions and pointers from somebody more familiar with the matter. Also maybe the community has more points to add to the list.

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.

[rauchg]

These are awesome suggestions. They're all planned. The first one will be in the wiki. The other two let's just improve the README!

[niksurff]

@rauchg just to clarify: Is somebody working on any of these points already? Otherwise I'll start putting some words on paper and we can go from there.

Also: README.md is getting fairly long already. Any thoughts on moving the bulk of the documentation into the wiki or even a docs folder served on a GitHub Pages site? Feels a bit like _ease of updating vs. ease of consumption_.

[rauchg]

@nikvm go ahead

Also: README.md is getting fairly long already. Any thoughts on moving the bulk of the documentation into the wiki or even a docs folder served on a GitHub Pages site? Feels a bit like ease of updating vs. ease of consumption.

I like to stick with README. If some sections are getting dense, we can link to Wiki pages that describe the feature or situation more.

[niksurff]

On it. PR with these and a hand full of other improvements coming soon-ish. ☕️

[yashha]

https://github.com/zeit/next.js/wiki/Getting-ready-for-production

[EnKrypt]

I'm not sure what's happening here, but I find it a bit hard to believe that a project with almost 25k stars on GitHub (at this moment) does not have proper documentation for some of it's methods after all this while.

Without proper documentation for render() and getRequestHandler(), many devs like myself are running blind.
Have I simply just missed it? I can't help but wonder whether the documentation is somewhere obvious and I've simply had a brain fart and overlooked it.

[michaelGregoire]

I agree. The documentation (or lack thereof) leaves something to be desired. Please… please… please… provide concise documentation of the framework classes and their APIs.

[mitko993]

Hello,

Just wanted to show my support for this issue. Documentation is really needed.
The current documentation consists of examples for different use cases but these don't cover all possible scenarios. We need documentation of the API.

[EnKrypt]

It is sad to see an issue from early 2017 still open and receiving comments with no response from the maintainers.

To get some perspective, this issue is now more than two and a half years old and my comment above dates back to almost year and a half ago.

I've learnt a lot since then, and I'd like to offer my two cents to anyone reading this :

• Github stars don't actually mean that much. This project now has almost 42k stars. A lot of projects have high number of stars and while they might indicate that the project isn't complete garbage, they don't indicate much else. The only thing a lot of stars tell you is that the project owners know how to market their project well enough to get those stars.

• Missing documentation is a red flag. How would you know how to use something, if the how isn't even adequately there? This was also an issue for a specific version of Webpack on launch, but they eventually fixed it. Refusing to fix it, or even completely ignoring requests to fix it is even worse. I understand open source works on the unpaid labor of those charitable enough to spend their free time, but this is a deal breaker for me. What's the point of this labor if a nice fraction of the audience don't even know how to use it?

• It's good to know the alternatives. I think I did eventually manage to get Next working the way I wanted it back in 2018 after many frustrating hours of trial and error with guesswork (I ran into more issues than just the bad documentation), but I wish I hadn't. I regret spending that much time on Next where I could have easily moved on to something else and had it set up for a fraction of the time and effort. But Next was the first popular tool I found that ticked all the boxes on my list, so I adamantly kept going. Even if you end up concluding that you need Next and only Next for your use-case, being aware of the competition is always useful.

While I've personally switched to Gatsby for static SSR, I won't be advocating it. Honestly, Gatsby isn't flawless either, and I don't want to tell you what to use, but I do want to help you get some perspective on picking tools like these.

It's hard to say if or when the project maintainers will even be adding the documentation we've asked for in this issue, so if you're here because it's holding you back, I only ask that you mentally weigh whether putting in the effort is worth more than biting the bullet and looking for something else.

[Timer]

We're currently in the process of rewriting our entire documentation from scratch, making it very comprehensive and reorganizing it for clarity.

[EnKrypt]

That sounds great! Better late than never I'd say.