UA-17470720-3

Jump to content


Photo
- - - - -

Documentation Request (more elaborate)


  • Please log in to reply
19 replies to this topic

#1 Bounty

Bounty

    Experienced Member

  • STV 4.0 Pro
  • PipPipPipPip
  • 64 posts
  • LocationNetherlands
Reputation: 11
Good

Posted 27 March 2015 - 04:42 AM

Hi,

 

I love STV4 and its manual. I particularly like the video's. Digging in and trying to modify everything to my liking it's easy to get lost having to dig in old forum questions (often regarding older versions). 

 

Therefore I request more / more elaborate documentation.

 

In particular:

- thoughts and inner workings behind STV

- how to properly hookup ones own code with the generated IB stuff

- creating custom cells, adding curly braced info to it

- customising headers, grouping, connecting new views etc

 

I'd also love more support for Swift (personally I am letting go of any objc code since Swift is so much easier in my opinion)

 

Finally, I'd propose to clean up the forums a bit. If you are working with STV4 and swift (like me) it is quite hard to dig through all the discussions about old versions, examples in objective-c, which is particularly difficult when one is unfamiliar with older versions and experience on 'how to hook up everything'.

 

Hope many more will recognise this need so time will be created to focus on these aspects as well..

 

 

 

 

 

 

 

 

 


  • Tarek likes this

#2 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 27 March 2015 - 08:57 AM

Hi Bounty,

 

Thank you so much for all your suggestions, we're definitely taking notes here :)

 

Would you please elaborate on the more Swift support part? Thanks again.



#3 Bounty

Bounty

    Experienced Member

  • STV 4.0 Pro
  • PipPipPipPip
  • 64 posts
  • LocationNetherlands
Reputation: 11
Good

Posted 27 March 2015 - 09:42 AM

Hi Tarek,

 

Sorry for not having been very clear about this. What I was referring to is examples in documentation and things like STV's Class Reference.

 

Regarding the latter: in Apple's developer library the is now an option to select the language (objective c, swift or both) as you can see in https://developer.ap...lass/index.html

 

I'd assume many swift users would be happy to learn about STV. Some of them might not have an extensive objective c background. They would benefit from a class reference in familiar swift language, as well as examples in swift. 

 

I understand this is not something that can be achieved in one day, because a lot of history has been build up. This also makes it a bit difficult to check out the forums, especially because lots of older STV versions are being discussed there as well. 

 

Personally I'd like a forum section dedicated to the latest STV4 with swift (and objective only for those still working in objective c exclusively). But then again, I understand the difficulty of maintaining and migrating. So consider this request a suggestion/hope...  ;-)

 

 

PS: I really like the video's you made. Would love a collection of (short) video's on how to get stuff done with STV, also explaining how to hook up code, create headers, delegation, custom views etc. Well done, love to watch and learn from you in this way!


Edited by Bounty, 27 March 2015 - 09:48 AM.


#4 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 22 April 2015 - 12:10 PM

I second this — — the manual as it stands look incomplete. There's nothing on using STV in code, nothing on actions, nothing on themes... — there's a link in the docs to a Customizing section but it goes nowhere. 

 

I've found myself downloading the old manual to use that as a reference. 

 

Comparing it now, it looks like you've only got as far as updating the first section of the old-manual — the rest is really needed! 

 

Also, the idea of moving the old vs new version forum posts into separate sections is a very good one — but finishing the documentation should come first. 



#5 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 23 April 2015 - 06:13 AM

Thank you so much Carlon, we're already working on Bounty's suggestions. We should be releasing some major updates after WWDC.



#6 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 23 April 2015 - 06:22 AM

Hey Tarek

 

Thanks for the reply but WWDC is another 2 months away. Surely it's possible to improve the manual in the interim...?!

 

4.0 was released in November. The manual hasn't been updated since then. It's shockingly incomplete.

 

For a premium product that's good enough. 

 

Please finish the documentation as a matter of urgency. 



#7 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 23 April 2015 - 06:32 AM

Hey Carton,

 

The idea behind the post WWDC updates is to incorporate all the new features in the updated docs. You guys kindly let me know are areas where you need urgent help and we'll give that priority roll out.



#8 Bounty

Bounty

    Experienced Member

  • STV 4.0 Pro
  • PipPipPipPip
  • 64 posts
  • LocationNetherlands
Reputation: 11
Good

Posted 23 April 2015 - 06:42 AM

Hi Carlton,

 

I agree that good documentation is very helpful and would solve many questions that might otherwise needlessly end at this forum. I fully understand your point, but also want to say: please give Tarek a bit of slack, as he has a lot on his plate. If you get stuck, post on this forum, Tarek and others provide help rather quickly (for which I at least am very grateful(. 

 

Having said that, I really hope the documentation will get updated and improved. Good documentation can be a big timesaver for all, reduces the amount of 'newbee questions' on the forum and above all...  make coding so much more fun. :-)

 

* listening to that Gun's n' Roses song ;-) *

 

PS: @Tarek, with documentation in progress, maybe it would be helpful to post a short 10 minute movie about a certain topic every week?


Edited by Bounty, 23 April 2015 - 06:45 AM.

  • Tarek likes this

#9 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 23 April 2015 - 07:29 AM

Hi Bounty

 

I take your point: it's great Tarek participates in the forums — but as soon as you need to go to a forum or look at the source code to work out what's going on that's time down the drain. STV's selling point is saving time — the lack of documentation undermines that. (And the time between November and now is long enough already — I'm not saying it should necessarily be perfect but it should be a lot further along than it is.)

 

Tarek thanks for the offer to prioritise. I understand you want to include changes from WWDC but when they come you'll be coding and the docs won't get the attention then — so it needs to be now :-)

 

Today I've spent a lot of time messing around with SCWebServiceStore and Definition — trying to understand how they relate to each other and SCDataStore and how to extend beyond the simple read-only web service example. 

 

The API docs are great — but the need a "Programming Guide" style overview to show you how all the bits fit together. The old docs are ok but not really what I wanted — to be honest they're a bit list-like — in that they do a lot of listing of API. Rather a good discussion of the architecture and a few worked examples so that when you go to the API docs they make sense — vs now having to crack open the source to see what's going on.

 

So you want to read-write a remote API? Here are the constraints, here's the outline of what you need to do, here's how you step down a level if your API doesn't fit our pattern. THAT would have taken a hour or so to go through and got me going more quickly. 

 

But that's just one area... 

 

STV is clearly powerful, and clearly well coded and conceived. But each area needs overview docs that make clear the lay of the land so that (again) the API docs make sense when you come to them — so that they can serve as the reference as intended. 

 

What areas in particular? How the various components sit together and interact. Actions. Customizing (all aspects). The limits of what's possible in IB — and how you drop down to code when you need to. — All of this stuff. The forums just cannot substitute for that — and the product is unfinished without it — no matter how good the coding.


  • Tarek likes this

#10 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 23 April 2015 - 08:04 AM

Thank you guys for all the feedback, I really appreciate it. We'll push to roll out a first phase with the same philosophy you described above in about 2 weeks. You guys can then rate that and let us know if that's what you're looking for and if any changes are needed to make the docs more helpful to you.


  • Bounty likes this

#11 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 23 April 2015 - 10:22 AM

Cool. Thanks for that commitment Tarek! 



#12 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 01 May 2015 - 05:22 AM

Hey guys,

 

Follow up: First phase of documentation updates should be available by next Mon (May 11th). Thanks again for all the feedback.



#13 Bounty

Bounty

    Experienced Member

  • STV 4.0 Pro
  • PipPipPipPip
  • 64 posts
  • LocationNetherlands
Reputation: 11
Good

Posted 01 May 2015 - 06:14 AM

Great! Looking forward to it :-)



#14 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 11 May 2015 - 12:03 PM

Dear all,

 

The STV user manual has been updated with a new "Understanding STV" section. Please check it out and let me know if we're on the right track and if that's what you were looking for. The new section aims to provide a general overview of the architecture of the STV framework, and is not meant to be a thorough discussion of any specific technical topic (other sections will be added for these based on your feedback).

 

Thank you very much!


  • Dave Guerin and wizgod like this

#15 Bounty

Bounty

    Experienced Member

  • STV 4.0 Pro
  • PipPipPipPip
  • 64 posts
  • LocationNetherlands
Reputation: 11
Good

Posted 11 May 2015 - 11:15 PM

Hi Tarek,

 

Thumbs up. In my view you are most definitely on the right track. I like the update, its addition is well written, clear and informative. Also, I highly appreciate the extra Swift code.

 

Thanks a lot!


  • Tarek likes this

#16 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 12 May 2015 - 06:00 AM

Hi Tarek. 

 

Nice update! I have a little moment to look at it and it seems good. As I work with it I can come back with specific points. 

 

The bit that I think is still missing is a discussion of SCDataStore. It defines a basic — and very simple — interface that the rest of the framework interfaces with. This is then implemented by the various subclasses. A more thorough discussion of that — and of how/where you make adjustments in subclasses of your own would be very handy. 

 

With that in place users would have a good reference for implementing against... (insert Persistence Library/DB/API of choice). 

 

Again, good work though! Do keep it up. :-)


  • Tarek likes this

#17 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 13 May 2015 - 11:11 AM

Thanks a lot guys, your input is much appreciated.

 

@carlton: Yes, SCDataStore was intentionally left out for the more advanced sections so as not to cause confusion to people trying to understand the general STV architecture. What I have in mind is developing some kind of an example within the documentation showing how to use SCDataStore to extend STV to interface with (say) SQLite directly (or any other service you guys have in mind).


  • ozie and wizgod like this

#18 carlton

carlton

    Starting Out

  • STV 5.0 Pro
  • Pip
  • 8 posts
Reputation: 4
Good

Posted 14 May 2015 - 12:11 AM

Hey Tarek — 

 

Yes, something like that sounds exactly right. 

 

I can see two simple, but fully worked, examples being sufficient.

 

One local — to SQLite as you say — whatever is simplest, really. (I guess it needs to be one step up from just using NSArchive and SCArrayStore — the point is to demonstrate a simple custom subclass.)

 

The second should be remote and implement the necessary methods on SCWebServiceStore. (This was where I spent a bit of time working out the details where an example would have helped.) Again you just want something simple here — the details of the networking layer don't want to get in the way.

 

The API that comes to mind is for GitHub's Gists — it's friendly and could demonstrate the full fetch/write/refresh loop without (hopefully) you writing too much code. I leave it with you to decide. :-)


  • Tarek and Everett like this

#19 Everett

Everett

    Ev

  • STV 5.0 Pro
  • PipPipPipPipPip
  • 191 posts
  • LocationMichigan
Reputation: 60
Outstanding

Posted 14 May 2015 - 02:55 PM

Great Job Tarek, just in time.  :) I think it would be very interesting to see an example for SQLite but I'd suggest SQLite wrapped by FMDB, would be better still.


  • Tarek likes this

#20 Tarek

Tarek

    Forum Admin

  • Administrators
  • 3670 posts
Reputation: 452
Popular

Posted 15 May 2015 - 08:11 AM

Thank you Ev.

 

It would actually be much easier to use FMDB, but I'd rather stick with something that ships natively and most people are familiar with. It's just the hassle of asking people to add another layer before being able to work out the provided examples. The important thing here is understanding the actual concept, which will enable you to connect STV to any other data source of your choice.






0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users