search

socrata / datasync

Desktop / Console application for updating Socrata datasets automatically.
http://socrata.github.io/datasync/
MIT License
79 stars 33 forks source link

Documentation versioning #119

Open shua123 opened 8 years ago

shua123 commented 8 years ago

For documentation at http://socrata.github.io/datasync/ consider adopting better version documenting. Currently the documentation is just continually updated, presumably kept up to match the newest release version. If someone is using an older version of DataSync it is not easy to figure out what parts of the documentation may be relevent to an older version and it is not easy to get to older versions of the documentation.

Consider adopting inline version information similar to the recent API documentation changes (https://dev.socrata.com/changelog/2015/11/25/soda-api-versioning.html).

Preferably also (or alternatively) utilize Readthedocs.org style setup that makes it easy to switch between documentation versions. readthedocs-versions

levyj commented 8 years ago

This is a really good point. Due to some of the backwards compatibility issues, needing to use older versions for a period of time or permanently is a real possibility.

From: Josh Kalov [mailto:notifications@github.com] Sent: Thursday, December 03, 2015 2:00 PM To: socrata/datasync datasync@noreply.github.com Subject: [datasync] Documentation versioning (#119)

For documentation at http://socrata.github.io/datasync/ consider adopting better version documenting. Currently the documentation is just continually updated, presumably kept up to match the newest release version. If someone is using an older version of DataSync it is not easy to figure out what parts of the documentation may be relevent to an older version and it is not easy to get to older versions of the documentation.

Consider adopting inline version information similar to the recent API documentation changes (https://dev.socrata.com/changelog/2015/11/25/soda-api-versioning.html).

Preferably also (or alternatively) utilize Readthedocs.org style setup that makes it easy to switch between documentation versions. [readthedocs-versions]https://cloud.githubusercontent.com/assets/1593537/11572283/ff32a000-99c5-11e5-87db-2583e6b75f70.JPG

— Reply to this email directly or view it on GitHubhttps://github.com/socrata/datasync/issues/119.

This e-mail, and any attachments thereto, is intended only for use by the addressee(s) named herein and may contain legally privileged and/or confidential information. If you are not the intended recipient of this e-mail (or the person responsible for delivering this document to the intended recipient), you are hereby notified that any dissemination, distribution, printing or copying of this e-mail, and any attachment thereto, is strictly prohibited. If you have received this e-mail in error, please respond to the individual sending the message, and permanently delete the original and any copy of any e-mail and printout thereof.

NithyaChandru commented 8 years ago

Thank you for brining this to our attention. We will take a look at our documentation for older versions of DataSync and find a good way to share that and the new documentation with you.

shua123 commented 8 years ago

There's been a couple releases since this issue was created and no movement on this. Is there an update? This is super simple to do so its confusing why there has been no progress.

shua123 commented 8 years ago

It needs to be cleaned up more but... http://datasync-historical.readthedocs.io/en/docs-1.7.2/ http://datasync-historical.readthedocs.io/en/docs-1.7/ http://datasync-historical.readthedocs.io/en/docs-1.6/ http://datasync-historical.readthedocs.io/en/docs-pre-1.6/

Built from docs-version branches at https://github.com/shua123/datasync