FlexUnit Documentation Status
boushley
What areas does everyone feel the project's documentation is lacking
in? If we could get a list going of areas needing better
documentation or tutorials we'ld like to see for the project that
would be great.
If this list already exists elsewhere, could you point me in the right
direction!
Aaron
Michael Labriola
Aaron,
Good question. A few things to start this discussion.
First, we just launched a flexunit support app on tenderapp:
https://flexunit.tenderapp.com/
We are going to try to shift support away from the forums and to hear
for a two reasons. First, it will give us a repository for answered
questions. Second, it will give us an idea where we continue to lack
documentation as we move forward.
Right now the docs on docs.flexunit.org are a bit of a free-for-all.
There is good stuff in the docs, but it is hidden amongst various
links and some of the best content is orphaned at the moment. I see
the docs needing to break down into a few areas:
1) Getting Started - This is a little more difficult than it should
be. I see the getting started having to cover several areas (these are
not in order or even all immediate goals, just starting the
conversation):
Getting the environment setup if you are using Flash Builder Premium
(where FlexUnit is already integrated)
Getting the environment setup if you are using an older Flex Builder,
FDT, IntelliJ, command line compiler, etc.
Getting the environment setup if you are using CI (and all of the
caveats that go with different platforms here)
Then I feel we need some walk-throughs of writing basic tests which
introduce terms, etc. along the way. One thing I haven't resolve in my
mind yet is how we teach people to write code that can be tested. In
my experience, that vast majority of people having trouble unit
testing have issues because the code they wrote cannot be broken into
units. I am not sure how we cover that, but somehow we must at least
describe it.
Joel Hooks has graciously agreed to start on this and coordinate it,
so I will let him discuss it here. Anyone who is interested in working
on it post a response here and let Joel coordinate with you.
From here we can get into structuring tests and hopefully round out
the basic things you can do with the testing framework
2) Features - We have a heck of a lot of features and things you can
do. We need to address these feature by feature, explain their
intended use case and provide examples... so, this might include small
things like expected errors to large things like async. It will also
somehow need to lead advanced devs toward the extensibility features
such as rules and runners
3) API docs. This one is the most interactive as we need to get better
docs and examples in the code. I have been trying to do this as we
have moved along but, unfortunately, it is a slow process. This is
going to be very interactive as the code is still in flux.
4) Tests. We can't underestimate the value of the tests. With the next
beta release, I hope to integrate a bunch of new and restructured
tests. However, more work needs to happen here and, eventually, I
would like to see documentation of the tests as these could become
example as well.
That's the idea. Anyone who wants to doc a feature or write tests for
a section can just ask and I will be glad to spend some time with you
explaining code, approach, etc. We can do this in Adobe Connect and
post it publicly so that it also becomes a rough part of the
documentation and a resource for writing.
Mike
Michael Labriola
Ah, one more thing. We also need to start seeing tenderapp with
questions. So, anyone feeling brave can start looking through posts on
the Adobe flexunit forum and adding them to FAQs and discussions on
tender. Just let me know that you are interested and I will add you as
support staff to the project.
Mike
boushley
me know if there are particular things I can help out with!
And Mike I would be more than happy to document sections of code that
are lacking, especially since it would give me a strong reason to take
a deeper dive into the code. Can you think of a feature that is
fairly stable and/or lacking in documentation? Or a feature that may
still be in flux but you would really like to see documentation on?
Thanks for the great post on the direction we're trying to go!
Aaron
Joel Hooks
Well Joel, when you start looking into the getting started section let
me know if there are particular things I can help out with!
And Mike I would be more than happy to document sections of code that
are lacking, especially since it would give me a strong reason to take
a deeper dive into the code. Can you think of a feature that is
fairly stable and/or lacking in documentation? Or a feature that may
still be in flux but you would really like to see documentation on?
Thanks for the great post on the direction we're trying to go!
Aaron
Michael Labriola
David Wolever
On 18-Jul-10, at 7:42 PM, Michael Labriola wrote:
> Then I feel we need some walk-throughs of writing basic tests which
> introduce terms, etc. along the way. One thing I haven't resolve in my
> mind yet is how we teach people to write code that can be tested. In
> my experience, that vast majority of people having trouble unit
> testing have issues because the code they wrote cannot be broken into
> units. I am not sure how we cover that, but somehow we must at least
> describe it.
IMO, this should be a secondary concern to getting solid FlexUnit
documentation in place; plenty of people[0] have written about
"writing testable code", but not very many have written about "how to
use FlexUnit to test code".
[0]: who I would link to, but I'm offline right now.
> Joel Hooks has graciously agreed to start on this and coordinate it,
> so I will let him discuss it here. Anyone who is interested in working
> on it post a response here and let Joel coordinate with you.
Awesome, thanks Joel.
I'd be happy to write a bit about parameterized testing (at least,
TestNG style parameterized testing — I've never really used the JUnit
style).
> 2) Features - We have a heck of a lot of features and things you can
> do. We need to address these feature by feature, explain their
> intended use case and provide examples... so, this might include small
> things like expected errors to large things like async. It will also
> somehow need to lead advanced devs toward the extensibility features
> such as rules and runners
I'd be up for writing (or at least cleaning up and expanding) the
documentation on Rules.
Joel Hooks
On Jul 19, 2010, at 11:00 AM, David Wolever wrote:
> IMO, this should be a secondary concern to getting solid FlexUnit documentation in place; plenty of people[0] have written about "writing testable code", but not very many have written about "how to use FlexUnit to test code".
I agree. Do you think progressive contextual examples is a good approach for the foundation to document around. I'm primarily thinking about the getting started portion. The examples could provide "testable code" examples, but the documents won't dig into explaining a bunch of those principles.
Michael Labriola
David:
Please provide those links when you have time. I understand that
writing testable code may be documented, however, 7/8 of all of the
questions I receive are not related to FlexUnit APIs but rather are
questions on how to write a unit test for something... Most of the
time the answer is "You can't" because the code is not testable.
Mike
Joel Hooks
Please provide those links when you have time. I understand that
writing testable code may be documented, however, 7/8 of all of the
questions I receive are not related to FlexUnit APIs but rather are
questions on how to write a unit test for something... Most of the
time the answer is "You can't" because the code is not testable.
Michael Labriola
Can do. Agreed, the google testing blog is awesome. Perhaps we just
need to create strategic pointers into it
David Wolever
On 19-Jul-10, at 1:56 PM, Michael Labriola wrote:
> Please provide those links when you have time. I understand that
> writing testable code may be documented, however, 7/8 of all of the
> questions I receive are not related to FlexUnit APIs but rather are
> questions on how to write a unit test for something... Most of the
> time the answer is "You can't" because the code is not testable.
Ah, ok — not having spent time answering questions, I didn't realize
that people expected FlexUnit to magically make their code testable
(feature request for 5.0?)
In that case, I'm wrong: the FlexUnit website is as good a place as
any for educating Flash/Flex devs on how to write testable code.
The only thing I would be concerned with is that I (and presumably
other moderately experienced developers) should be able to read about
"how to use FlexUnit" without having to sit through Testing 101.
And I've found the Google Testing Blog[0] to be one good resource.
Another (albeit dead tree) resource I've found helpful is Feather's
Working Effectively with Legacy Code[1]… But unfortunately it doesn't
look like it's on Google Books, so we can't link to it :(
[0]: http://googletesting.blogspot.com/ with eg, http://googletesting.blogspot.com/2008/08/by-miko-hevery-so-you-decided-to.html
[1]: http://books.google.ca/books?id=CQlRAAAAMAAJ&q=0131177052&dq=0131177052&hl=en&ei=AJRETPqNDNObnwf83Pi_Cw&sa=X&oi=book_result&ct=result&resnum=1&ved=0CC4Q6AEwAA
On 19-Jul-10, at 1:54 PM, Joel Hooks wrote:
> I agree. Do you think progressive contextual examples is a good
> approach for the foundation to document around. I'm primarily
> thinking about the getting started portion. The examples could
> provide "testable code" examples, but the documents won't dig into
> explaining a bunch of those principles.
That's sort of what I was thinking: it would be ideal (at least in
theory) if we could just give examples of common problems which have
been solved in a testable way.
Joel Hooks
On Jul 19, 2010, at 1:07 PM, Michael Labriola wrote:
> Can do. Agreed, the google testing blog is awesome. Perhaps we just
> need to create strategic pointers into it
Having tidy note blocks ( testable tips! <- ;) ) with links to details would be a good approach I think.
I was thrilled to see that is your topic for 360 btw. Sad on the same hand that I won't be there.
Michael Labriola
Totally agree that the 'how to test' material shouldn't interfere with
those wanting to know 'how do I use flexunit'
"people expected FlexUnit to magically make their code testable
(feature request for 5.0?) "
However, they don't want to make their code testable, rather they wish
it to do magic and figure out how to test it.
Mike
On Jul 19, 1:13 pm, David Wolever <wolever.li...@gmail.com> wrote:
> On 19-Jul-10, at 1:56 PM, Michael Labriola wrote:
>
> > Please provide those links when you have time. I understand that
> > writing testable code may be documented, however, 7/8 of all of the
> > questions I receive are not related to FlexUnit APIs but rather are
> > questions on how to write a unit test for something... Most of the
> > time the answer is "You can't" because the code is not testable.
>
> Ah, ok — not having spent time answering questions, I didn't realize
> that people expected FlexUnit to magically make their code testable
> (feature request for 5.0?)
>
> In that case, I'm wrong: the FlexUnit website is as good a place as
> any for educating Flash/Flex devs on how to write testable code.
> The only thing I would be concerned with is that I (and presumably
> other moderately experienced developers) should be able to read about
> "how to use FlexUnit" without having to sit through Testing 101.
>
> And I've found the Google Testing Blog[0] to be one good resource.
> Another (albeit dead tree) resource I've found helpful is Feather's
> Working Effectively with Legacy Code[1]… But unfortunately it doesn't
> look like it's on Google Books, so we can't link to it :(
>
> [1]:http://books.google.ca/books?id=CQlRAAAAMAAJ&q=0131177052&dq=01311770...
Michael Labriola
Yeh, also doing a similar talk at Max, albeit to a slightly different
audience. I think it is needed in the community.