Split documentation into pages

[cbetta]

The documentation was getting massive and hard to search. This helps split it down into smaller pages that can be separately linked to.

[leggetter]

I'm not convinced that this improves things. What are the arguments for splitting up the docs?

[cbetta]

1. The page was getting extremely long and hard to get a quick overview on
2. Pages can now be linked to directly
3. Pages give people a clearer insight into what a specific namespace does
4. This also means we can add some more explanation as to what certain segments do without making the docs even more long. For example applications and linking don't really explain what applications are yet.
5. It pushed the contributing instructions way down the README.

But if you disagree I'm happy to revert it again

[leggetter]

The page was getting extremely long and hard to get a quick overview on

I think that's what the Overview section should be for.

Pages can now be linked to directly

You can also directly link to headings.

Pages give people a clearer insight into what a specific namespace does

I'm not sure how separating out the docs helps with this. Any more info?

This also means we can add some more explanation as to what certain segments do without making the docs even more long. For example applications and linking don't really explain what applications are yet.

The official Nexmo documentation should provide that detail.

It pushed the contributing instructions way down the README.

Fair point. But I would expect to find that in https://github.com/Nexmo/nexmo-cli/blob/master/CONTRIBUTING.md

I'm still open to being convinced. But my opinion is that we presently live in a world of the 1-pager guide.

[cbetta]

Interestingly I deal with a lot of projects that do not live by the 1-pager guide rule. They instead push a lot to the Wiki. The downside of the wiki is that:

1. It is not searchable easily on GH
2. It does not get pushed to npmjs.com

Hence why I pushed thing into separate pages in a docs folder instead.

Personally I'm in favor of concise docs as they reduce cognitive load (less info on screen etc) and indicate simplicity. The same reason why most API docs will have a landing page with a basic use case and then links to the reference docs.

I guess it mostly comes down to personal preference though. Do you have anything specifically against splitting the docs?

[leggetter]

Interestingly I deal with a lot of projects that do not live by the 1-pager guide rule.

Do you have some good examples/links?

They instead push a lot to the Wiki

Yeah, meh!

I guess it mostly comes down to personal preference though.

"preference" - hopefully created through experience of what works. Is there a way that we can capture what others think? A Twitter poll?

Do you have anything specifically against splitting the docs?

1. CTRL+F / CMD+F is your friend in docs. By moving docs to separate pages you remove the benefit of the in-built feature.
2. There are visual indicators in a page that help skimming. A good table of contents and clear headings really help. I find it easier to explore (less effort) by scrolling over navigating (clicking, back, forward).

[cbetta]

Ok you convince me. I'll revert