How can we improve ATF documentation?

[gstaas]

@gstaas @vkashkash @ColinCren @silvesthu @RomainBL @JelleVM @pdrasko @vorptronica @fuleshu @mstum @RoyAwesome @lordmortis @StirfireStudios

Because of your interest in ATF, we want your feedback to help us improve ATF documentation.

The fundamental question is: What would help you learn and use ATF? In reflecting on this, you might want to consider:

• What would help you get started using ATF?
• What topics would you like to see covered in the documentation that aren't currently?
• What parts of the documentation need the most improvement?
• How can we improve documentation organization?
• Do you like the formatting of document pages? Any suggestions? More graphics and screen shots? Color usage?
• Access: Do you like online documents? A wiki? Would you prefer downloaded documentation? In what formats: PDF, ePub, mobi, others?
• What other items would you find useful: More test code? Tutorials, what topics? Reference cards, that is, a few pages containing key information? FAQ? More videos, what topics? Examples, what areas? More samples, what areas?

Please send responses to gary_staas@playstation.sony.com by Friday, October 3, 2014. Or just leave your comments on this issue. Thanks!

[JelleVM]

I found the learning curve of ATF incredibly steep (though worth it in the end), compared to learning e.g. Qt. I think there are several things that ATF could greatly benefit from to get people started quickly:

• Video tutorials: This is actually the most important one, I think. ATF has lots of interfaces and services of which it is not immediately obvious what they do or how to make them work. Browsing through all examples to find which one uses them and how gets really tedious. And sometimes, even if you think you get it, you might use a component in a slightly different way it was intended. I would greatly benefit on small (2--5 minute) tutorials on how to use the components best. And DOM deserves some special attention.
• On-line searchable Wiki-style documentation. I much prefer this over downloadable pdf/chm files. I've always got my internet browser at hand.
• Lots of small sample projects: what I very much like about e.g. Qt is that they have lots of very small sample projects that show off just one component or feature. You can also browse them by tag. Something similar for ATF would greatly reduce the learning curve, as you'd have ready-made examples demonstrating behaviour in a contained way. (I do understand this is a lot of work though.)

[mstum]

I haven't had much chance to play around with ATF, but I agree with Jelle about Sample Projects. There is a lot of cool stuff in there, it's just overwhelming at first. The clarifications from #6 helped a lot. May be a 5 Minute Elevator Pitch/10000 feet overview video could help.

[JelleVM]

Ok, I gave it some more thought, and I think that the hardest part of learning ATF for me was how to connect all the strings, and to see what components do exactly what. For example:

• If I have a CommandService, where do I add the commands?
• How to make a context listener: i.e. to what classes do I add the appropriate interfaces (how do I find these if I don't know what they're called?), how do I subscribe to the appropriate events?
• Can I make an application that does not use the default Docking Layout? Can I then still import all Services in the same way?
• I want to use the ContextMenuService; how do I tell it what buttons to add to which context? How is it aware of the context in the first place?
• What do those tons of XAML Behaviours actually do? (In Atf.Gui.Wpf/Behaviors)
• The Adaptable stuff seems cool, but how is it different from simply using inheritance and the C# call as.
• How do I use the SearchAndReplace stuff?
• DOM. Just, DOM.

(This is by no means an exhaustive list.) In the end, I found the answer to nearly all the above (I think/hope :smiley:), but all of these combined make for a very steep learning curve. What would be really good, would be a little sample project and/or video tutorial making that sample, in which you show off 1 behaviour/service at the time. Your users can then put together the blocks they need into their own application.

[silvesthu]

Besides ideas above, I think not all developer is not going to start a new project based on ATF. Difficulty of cooperating is another important aspect for users. So,

• It would be better that the dependency between each part is shown in a graph. Then user may decide whether to adopt this library before go deep into the structure of it.
• It would be nice that data exchange is easy enough between system that is already in use. Such as providing an overview of data structures of object like mesh and animation and alter the formats of serialization.

Since I haven't read through all parts of ATF, apologize for any misunderstanding.

[gstaas]

@silvesthu I want to make sure I understand your points.

• Regarding dependency of parts, what parts do you mean? Classes? Components? Something else?
• What do you mean by "Data exchange"? What kind of data? You mention an overview of objects like mesh and animation, but I don't understand the connection, or what that has to do with serialization format. Thanks!

[JelleVM]

Also: more WPF examples. :-) Everything is in WinForms at the moment, which in my opinion is becoming increasingly obsolete with the awesomeness WPF provides.

[silvesthu]

@gstaas Apologize I haven't read through much detail. Here's my thoughts.

• Both classes and components : by dependency I meant how much of the component
  or whole ATF I need to know before I could start to use anything
  • e.g. Which class should I start with if I want to use DocklingsWindow, all file below Docking folder? Or it depends on other controls implemented by ATF ?
• Maybe property is a better example for the second one.
  • Say I've already adopt some other library which provides type like vector, matrix etc. Then I want to use PropertyEdting in ATF. Need I convert it to some xml format or I could use the object directly ?

[vorptronica]

I second the need for WPF documentation. The current single WPF example is woefully inadequate for a newbie to MEFand ATF. A conversion doc that gets into more details of how you might convert existing samples to WPF would be welcome as well. -Len

[julianneh]

@JelleVM @vorptronica Thanks for the feedback on WPF. More WPF content is on the way! The existing sample app will be enhanced, a new sample app or apps are coming (either a full-featured showpiece app or a bunch of bite-sized samples, or eventually both), and the documentation will be getting some major improvements too. The goal is to bring our level of WPF support up to parity with our WinForms support. Most of our internal customers have been using WinForms so that's been the main focus of our efforts in the past, but I think that will start to change as we bring WPF up to first class citizen status and make it a more attractive option. I agree - WPF is the future!

[JelleVM]

Yeay, great news! I already mentioned this, but I don't think it can be overstated: having many 'bite-sized' samples is generally much more instructive to the newbie than a full show piece. Many programmers can put building blocks together to make something new (and they'll enjoy it), but filtering all the useful bits in a complicated beast like the LevelEditor can be a nightmare. And having both is better, of course. :D

[RoyAwesome]

Personally, I ran into a big issue trying to figure out how I could do certain things. I had a document that I wanted to create multiple editors for (For example, a text file that I could either view as plain text, or parse it and show it as a bunch of game objects and edit that way). I also ran into issues writing my own serialization format (I was writing a Custom Map Editor for Dota 2, and they have their own notation for game objects).

The examples are pretty great, but trying to do anything outside of what those examples show is incredibly esoteric and it's very unclear what things can do or how they interop with eachother.

[gstaas]

I've been modifying the documentation in the wiki to address some of the issues I've seen here.

• Getting Started has been totally redone to give users a better introduction to ATF and give them a path to follow to learn ATF. Some of this material comes from the old Getting Started PDF doc, which was dated and now obsoleted by this new material. I've tried to make things easier to find. For instance, a video showing a high level view of ATF had been asked for, and one already existed, so I highlighted this in the new Getting Started page. The sidebar has also been changed to provide better access to key areas.
• A How To section has been added. It was hard to find such information previously. This also includes a section of how to use the documentation and how to search through it.
• The Programmer's Guide was also restructured to present the key areas an ATF user needs to know, instead of overwhelming a user with a large number of topics.
• I added a Tutorials section, which only has two items now, and I plan to expand this.
• The Readme.md file in the main GitHub page has also been simplified and links to key places in Getting Started and other sections.

I'm now working on ideas for "small projects" showing how a single component or feature works. In addition, as new WPF content is added to ATF, I'll be writing about it.

Your ideas on improvements and comments are very welcome!

[kiwidoggie]

I've been trying to figure out https://github.com/SonyWWS/ATF/wiki/Value-Editors-and-Value-Editing-Controls for the longest time. I am using WPF and it seems that the WPF counterparts of ATF don't have any clear documentation with the variations from the WinForms counterparts. I'm not sure if I'm just missing it, but I've been doing much trial and error with ATF in WPF.

EDIT: I also am not using DOM.

[abeckus]

The WPF/ATF lacks features, docs, robustness, it is more of a work in progress than full feature framework. WinForm/ATF is under development for many years so it is more robust and feature complete than WPF counter part. Unfortunately, at this point there is no plan to improve WPF/ATF. Winform/ATF offers direct2d, skinning and lots of control and editors.

note: using ATF without DOM would be harder since large part of ATF implemented using DOM. Alan.