Post History

Source: https://writers.stackexchange.com/a/33589
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I can understand the reasoning from both sides. A complete _quick start_ is essential to ensure that the reader has sufficient information to see the product running correctly, and is able to demonstrate and present a sample default use case to the user, without these the casual reader will not know whether to bother reading further because they will be unable to understand what the product really does.

However, once you have a basic understanding of the product, the potentially lengthy _quick start_ set-up, prerequisites and so on is merely bloat compared to the reader getting down to the information they really need.

The answer here is to hive the _quick start_ into a separate section or document, and offer sample code either as part of your product or available in an online hosted repository such as GitHub. This would mean that the full set up details could be left in the `README` for example, and the _quick start_ in the API reference could be reduced to _Download the code and follow the instructions_

Compare and contrast the following level of detail on the Java **Date-Time API**

- Overview: [https://docs.oracle.com/javase/tutorial/datetime/overview/design.html](https://docs.oracle.com/javase/tutorial/datetime/overview/design.html)
- API Reference: [https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html](https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html)
- Demo Code: [https://github.com/sualeh/java8-timeapi-examples](https://github.com/sualeh/java8-timeapi-examples)

The first two would be found within your reference documentation, the third one would be a link to avoid bloat.

The audience may well be experienced developers, but they will not have full understanding of your product, and trust me they will appreciate having a Hello World.

Original score: 4