Adding an initial Guide section to the online documentation #595
Conversation
There was a problem hiding this comment.
Hello @BradLarson Just sharing my 2 cents, hope you don't mind.
May I recommend a quote from Chris (@lattner) from a talk (don't remember which one): "Swift was conceived as a full-stack programming language".
I'd also recommend mentioning type safety as a core feature (looking at my notes: Swift is "compiler-friendly and designed to be fast from the beginning.") Would it also make sense to emphasize that Swift is fast and human-friendly? I see "fast" being mentioned once here already though.
I've also got a quote from Jeremy H in my notes: "...the first serious effort I’ve seen to incorporate differentiable programming deep in to the heart of a widely used language that is designed from the ground up for performance." I see "differentiable" is mentioned several time already and maybe it can make sense to add the "effort... to incorporate... in to the ... language" 🤷
Also, maybe it makes sense to have the Why S4TF section come before Why Swift. The former (this section) mentions that the project has first-class lang and compiler support + autodiff <- what a lot of folks in research care about.
I think not many people read the whole post/article/guide when they scan text for the first time, so having a section on the S4TF system in the beginning may make more sense.
Thanks again for putting this together 👏
| Swift has the audacious goal of spanning all the way from low-level systems programming to | ||
| high-level scripting, with a focus on being | ||
| [easy to learn and use](https://www.apple.com/swift/playgrounds/). |
There was a problem hiding this comment.
May I recommend a quote from Chris (@lattner) from a talk (don't remember which one): "Swift was conceived as a full-stack programming language".
I'd also recommend mentioning type safety as a core feature (looking at my notes: Swift is "compiler-friendly and designed to be fast from the beginning.") Would it also make sense to emphasize that Swift is fast and human-friendly? I see "fast" being mentioned once here already though.
I've also got a quote from Jeremy H in my notes: "...the first serious effort I’ve seen to incorporate differentiable programming deep in to the heart of a widely used language that is designed from the ground up for performance." I see "differentiable" is mentioned several time already and maybe it can make sense to add the "effort... to incorporate... in to the ... language" 🤷
| ## Why Swift for TensorFlow? | ||
|
|
||
| Swift for TensorFlow is a new way to develop machine learning models. It | ||
| gives you the power of | ||
| [TensorFlow](https://www.tensorflow.org) directly integrated into the | ||
| [Swift programming language](https://swift.org/about). We believe that | ||
| machine learning paradigms are so important that they deserve | ||
| **first-class language and compiler support**. |
There was a problem hiding this comment.
Also, maybe it makes sense to have the Why S4TF section come before Why Swift. The former (this section) mentions that the project has first-class lang and compiler support + autodiff <- what a lot of folks in research care about.
I think not many people read the whole post/article/guide when they scan text for the first time, so having a section on the S4TF system in the beginning may make more sense.
There was a problem hiding this comment.
Great start! Let's merge this so we can see if the guide shows up properly on https://www.tensorflow.org/swift.
Thank you @8bitmp3 for your feedback! We'll definitely keep your suggestions in mind. I think we'll go ahead and merge now to verify the end-to-end documentation workflow, and then we can make incremental edits later.
|
@8bitmp3 - As Dan said, thanks for the comments. As a first step, I merely copied the descriptions we'd used elsewhere to create a starter document. The intent is that we'll modify and enhance this and add new guide sections once we verify that this gets formatted correctly over at tensorflow.org/swift. When it comes to organization, I'd really like to have entry points for both people who know Swift but are new to ML and those who know ML but are new to Swift. I organized this with the latter in mind so that we explain why they should be excited about Swift first, then what we're doing with Swift for TensorFlow. I'm sure there are better ways of stating this, however. I'm going to verify that everything is formatted correctly tomorrow, but after that point pull requests that add to or modify this wording would certainly be welcome. I'm going to follow on with individual guide pull requests as I have them ready. |
As a start to expanded documentation at tensorflow.org/swift, this adds a Guide section with a quick overview of Swift and Swift for TensorFlow. These sections were drawn from our current documentation in the front-page Readme here, as well as the Swift for TensorFlow design overview.
In addition to the overview documentation, the link to the Swift APIs has been updated to point to the correct repository, and a link to tensorflow/swift-models has been added.
Other documents will be added in subsequent pull requests.