Opened 8 years ago

Closed 3 years ago

#12785 closed enhancement (patchwelcome)

[SDK] Missing and index.html / further info within root

Reported by: lazaridis_com Owned by: dante
Priority: high Milestone: 1.11
Component: General Version:
Keywords: Cc:
Blocked By: Blocking:

Description

The download page (http://dojotoolkit.org/download/) mentions:

"Dojo Toolkit SDK:

An "SDK" (Software Development Kit) raises several expectations.

My expectation was to find an index.html, which says some basics, and guides me through the sources, explaining the directory structure, links to setup requirements for the demos and tests, and finally links to some demos an test for execution.

The suggestion is to start with a basic index.html (or at least README.TXT).

Alternatively, you could change the wording from "Dojo Toolkit SDK" to "Dojo Toolkit Sources with Demos and Tests", avoiding this way to raise the expectation of an SDK.

Change History (8)

comment:1 Changed 8 years ago by dante

Milestone: future
Owner: set to dante

I agree with this ticket. I did have at some point a very simple README.html which was s sort of quickstart guide for base/core functionality, but never actually committed it. It had links to dijit tests, and some select dojox projects, as well as live examples of Dojo animations/ajax/events (base type stuff)

A better README in the root of the release providing offline instruction for use might be a good idea. Currently the views/ checkout only explains why there are no files in the folder.

comment:2 in reply to:  1 Changed 8 years ago by lazaridis_com

Replying to dante:

![...]

A better README in the root of the release providing offline instruction for use might be a good idea.

Yes. And don't forget: better documentations are produced by collaboration of experts and newcomers (which simple see the teach-in barriers the experts cannot see). And dojo itself can be used to build very special offline-documentation / navigation within and SDK. But for the start, one simple file with the requirements for the tests / demos would be possibly enough.

Currently the views/ checkout only explains why there are no files in the folder.

I did not understand that comment!

comment:3 Changed 8 years ago by Adam Peller

We really ought to maintain as much of this on the website as possible. A simple link to the website should do.

comment:4 in reply to:  3 Changed 8 years ago by dante

Replying to peller:

We really ought to maintain as much of this on the website as possible. A simple link to the website should do.

I disagree, a single quick regression-test-like README.html describing the current system/structure/hints on where to find things (like hey, look in tests/* to browse) in the SDK download would be very helpful to newcomers. Also links back to the full documentation and API ref from within the README itself would be A Good Thing (tm) imo

comment:5 Changed 8 years ago by Adam Peller

just another redundant file to get out of date. we used to do this, and that's what happened. let's not repeat that mistake. keep it simple.

comment:6 Changed 8 years ago by Adam Peller

perhaps we just need this information organized in a more approachable way on our site with a landing page somewhere that is the equivalent of the readme/gettings started doc you want?

comment:7 Changed 8 years ago by lazaridis_com

"Keep it simple". I agree with this. Simple, for the developers and for the users.

Because we are talking about a very basic README for the no.1 java-script-toolkit, the "unbeatable one".

If the source tree and the website are organized properly, the SDK can be auto-generated. There would be no duplicate effort at all - the maintenance effort could even be reduced.

As for the index.html (or README.HTML) a tiny draft example, which contains some suggestions.

DOJO TOOLKIT SDK

A few notes to the SDK.

 * several demos work from the filesystem, others need a server to run
 * you can find example code by looking at the tests within:
   * dojo/tests (centralized for all subsystems/modules)
   * dijit/tests (centralized for all widgets)
   * dojox/*/tests (each subsystem has its tests)

 * To run all the tests in an automated manner
   * you need to have java installed
   * you need to do this and that
   * see /jam/dojo/util/doh

 * The full api documentation is located here:
   * http://the-dojo-api
   * (offline version is scheduled for the SDK 2.0)

 * For community support, visit
   * http://

 * For commercial support, visit
   * http://
 

comment:8 Changed 3 years ago by dylan

Milestone: future1.11
Resolution: patchwelcome
Status: newclosed

Dojo has had a decent README for a while. Pull requests are welcomed to improve it.

Note: See TracTickets for help on using tickets.