You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Martin Heidegger <mh...@leichtgewicht.at> on 2012/02/10 17:43:20 UTC
[RT] Documentation (split from: Awesome User Experience)
Hello Francis
I think you are talking more about developer experience than end-user
experience.
The wiki seems a good start for documentation to me but I agree that it
has some serious drawbacks.
For example: we can not easily include swf's and AS3 code formatting is
sub-par. But i think if those requests are
raised to the infrastructure team then they will be dealt with. This
would result in following documentation locations:
*) Wiki: edited documentation, documentation about concepts with example
section
*) Blog: Time-related documentation: Changes/News
*) API-Docs: Generated API documentation
It would be not so hard to provide something like the PHP Ninja manual
[1] that sets up on the online data.
The only problem I see with the wiki solution is the translation. I
personally think "just english" is enough. However: For some reason
japanese developers (as a example) seem to be really trying to translate
everything and I am not yet sure how this could be done with the wiki.
However: this raises another question:
@Adobe: I assume that the Flash Player AS3 documentation will stay at
the Adobe site:
Do you plan to submit the Flex documentation (not just api docs) to apache?
Might that include Tour De Flex?
What system/format does it use?
Can the community help with that?
yours
Martin.
[1]
https://chrome.google.com/webstore/detail/clbhjjdhmgeibgdccjfoliooccomjcab
On 11/02/2012 01:23, David Francis Buhler wrote:
> I'd like to see the examples and documentation be part of an improved,
> cohesive 'brand' outlined. The rest of the outline I agree with.
>
> Someone else had suggested the idea of emulating the
> examples/documentation Sencha/JQuery use, which I second. Likewise,
> Google does an excellent job with http://tour.golang.org/
>
> I always found Adobe to offer too many alternatives to finding information.
>
> Examples:
> -Adobe offered too many Flex examples in the help.adobe.com site made
> accessing the information slow and painful. Future hiding of the
> Examples until the user clicked a button made 'seeing' the examples
> more involved.
> -The Help Docs had poor SEO. Questions asked about technical problems
> have a certain language, and the page-titles needed to reflect the
> language developers use to search out solutions to problems.
> -The Help Docs were longer than necessary.
> -Tour De Flex's User Experience did not reflect how people seek out
> information. It did not offer a linear evolution of 'challenges' or
> 'difficulty'. Examples often error out.
> -Adobe Community Help provided too many search options, that did not
> reflect an understanding of how people look for information.
>
> -Buhler
>
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
On 11/02/2012 07:00, Ariel Jakobovits wrote:
> Regarding asdocs, will we be able to reliably point users to the Flash Player AS3 documentation from our imported Flex doc site?
Of course not. The Flash Player as well as the AS3 Language are not
planned to be submitted to Apache.
However: I, personally, see the possibility that Adobe might change its
mind if we really "hit it off" as they say.
yours
Martin.
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Ariel Jakobovits <ar...@yahoo.com>.
Regarding asdocs, will we be able to reliably point users to the Flash Player AS3 documentation from our imported Flex doc site?
Ariel Jakobovits
Email: arieljake@yahoo.com
Phone: 650-690-2213
Fax: 650-641-0031
Cell: 650-823-8699
________________________________
From: Martin Heidegger <mh...@leichtgewicht.at>
To: flex-dev@incubator.apache.org
Sent: Friday, February 10, 2012 8:43 AM
Subject: [RT] Documentation (split from: Awesome User Experience)
Hello Francis
I think you are talking more about developer experience than end-user experience.
The wiki seems a good start for documentation to me but I agree that it has some serious drawbacks.
For example: we can not easily include swf's and AS3 code formatting is sub-par. But i think if those requests are
raised to the infrastructure team then they will be dealt with. This would result in following documentation locations:
*) Wiki: edited documentation, documentation about concepts with example section
*) Blog: Time-related documentation: Changes/News
*) API-Docs: Generated API documentation
It would be not so hard to provide something like the PHP Ninja manual [1] that sets up on the online data.
The only problem I see with the wiki solution is the translation. I personally think "just english" is enough. However: For some reason japanese developers (as a example) seem to be really trying to translate everything and I am not yet sure how this could be done with the wiki.
However: this raises another question:
@Adobe: I assume that the Flash Player AS3 documentation will stay at the Adobe site:
Do you plan to submit the Flex documentation (not just api docs) to apache?
Might that include Tour De Flex?
What system/format does it use?
Can the community help with that?
yours
Martin.
[1] https://chrome.google.com/webstore/detail/clbhjjdhmgeibgdccjfoliooccomjcab
On 11/02/2012 01:23, David Francis Buhler wrote:
> I'd like to see the examples and documentation be part of an improved,
> cohesive 'brand' outlined. The rest of the outline I agree with.
>
> Someone else had suggested the idea of emulating the
> examples/documentation Sencha/JQuery use, which I second. Likewise,
> Google does an excellent job with http://tour.golang.org/
>
> I always found Adobe to offer too many alternatives to finding information.
>
> Examples:
> -Adobe offered too many Flex examples in the help.adobe.com site made
> accessing the information slow and painful. Future hiding of the
> Examples until the user clicked a button made 'seeing' the examples
> more involved.
> -The Help Docs had poor SEO. Questions asked about technical problems
> have a certain language, and the page-titles needed to reflect the
> language developers use to search out solutions to problems.
> -The Help Docs were longer than necessary.
> -Tour De Flex's User Experience did not reflect how people seek out
> information. It did not offer a linear evolution of 'challenges' or
> 'difficulty'. Examples often error out.
> -Adobe Community Help provided too many search options, that did not
> reflect an understanding of how people look for information.
>
> -Buhler
>
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Alain Ekambi <ja...@googlemail.com>.
@Martin
Unfortunately the code of that application wont help much i think.
Simply because the application was not written in AS3/MXML but in Java
using GWT.
I was talking more about the structure of the app which was inspired from
the Ext-GWT explorer.
2012/2/10 Martin Heidegger <mh...@leichtgewicht.at>
> On 11/02/2012 01:55, Alain Ekambi wrote:
>
>> We have create something similar to the EXT-GWT explorer for our product
>> Gwt4Flex. ( http://www.gwt4air.appspot.**com/<http://www.gwt4air.appspot.com/>)
>>
>> Something in that direction would definitly be usefull.
>>
> It would be awesome if you could publish the code under a APL compatible
> license under github so it could be improved.
>
> yours
> Martin.
>
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
On 11/02/2012 01:55, Alain Ekambi wrote:
> We have create something similar to the EXT-GWT explorer for our product
> Gwt4Flex. ( http://www.gwt4air.appspot.com/ )
>
> Something in that direction would definitly be usefull.
It would be awesome if you could publish the code under a APL compatible
license under github so it could be improved.
yours
Martin.
RE: [RT] Documentation (split from: Awesome User Experience)
Posted by "Michael A. Labriola" <la...@digitalprimates.net>.
>>I'm curious how Open-Source projects handle the localization of documentation.
Before Adobe started the process of donating Flex to Apache, Spoon was working with them to open the localization of the framework and eventually docs to the community. We can see if Adobe is willing to donate any of the work done so far.
Mike
Notice: This transmission is intended only for the use of the individual or entity to which it is addressed and may contain information that is privileged or confidential. Any dissemination, distribution or copying of this transmission by anyone other than the intended recipient is strictly prohibited. If you have received this transmission in error, please notify the sender immediately by e-mail or telephone and delete the original transmission. Thank you.
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
On 11/02/2012 02:56, David Francis Buhler wrote:
> I'm curious how Open-Source projects handle the localization of documentation.
- Every system does it differently, this can be handled in a lot of ways.
I structure it for me like that:
- If documentation is deployed with the release of a project then every
"localization team" has time
to the release to add documentation and either they deploy with
untranslated parts or deploy
the translated parts once each translation is done.
- If the documentation is on a global service (homepage) then usually
the english page is first there
and the translators translate as they pass by. (See php documentation).
- Projects that do not change over a long time due to their simplicity
(small JavaScript projects) usually
can have one documentation and the documentation gets a version related
to but not similar to the
project.
API-doc translation is something that is missing in the FLEX SDK for
years now - I had particular difficult discussions about that in the
Java Community.
I have two concepts for that lying around somewhere.
If we have wiki it would work like:
> ...ng Tour de Flex, I'm not sure how effective it is.
I am not saying that we should continue it, I have certainly not used it ...
> If people have found the application to be helpful, I'd be interested in hearing more.
Me too.
yours
Martin.
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by David Francis Buhler <da...@gmail.com>.
Martin,
My apologies for thread-hijacking.
I'm curious how Open-Source projects handle the localization of documentation.
My understanding is that Adobe intends to donate the Tour de Flex
application, per another thread. With all due-respect to the efforts
of those involved with developing Tour de Flex, I'm not sure how
effective it is. If people have found the application to be helpful,
I'd be interested in hearing more.
@Alain,
Your explorer is excellent for providing examples. The hierarchy, I
think if effective.
On Fri, Feb 10, 2012 at 12:10 PM, Alain Ekambi
<ja...@googlemail.com> wrote:
> Looks like my post did not get through ....
>
> 2012/2/10 Alain Ekambi <ja...@googlemail.com>
>
>> We have create something similar to the EXT-GWT explorer for our product
>> Gwt4Flex. ( http://www.gwt4air.appspot.com/ )
>>
>> Something in that direction would definitly be usefull.
>>
>>
>>
>> 2012/2/10 Martin Heidegger <mh...@leichtgewicht.at>
>>
>>> Hello Francis
>>>
>>> I think you are talking more about developer experience than end-user
>>> experience.
>>>
>>> The wiki seems a good start for documentation to me but I agree that it
>>> has some serious drawbacks.
>>> For example: we can not easily include swf's and AS3 code formatting is
>>> sub-par. But i think if those requests are
>>> raised to the infrastructure team then they will be dealt with. This
>>> would result in following documentation locations:
>>>
>>> *) Wiki: edited documentation, documentation about concepts with example
>>> section
>>> *) Blog: Time-related documentation: Changes/News
>>> *) API-Docs: Generated API documentation
>>>
>>> It would be not so hard to provide something like the PHP Ninja manual
>>> [1] that sets up on the online data.
>>>
>>> The only problem I see with the wiki solution is the translation. I
>>> personally think "just english" is enough. However: For some reason
>>> japanese developers (as a example) seem to be really trying to translate
>>> everything and I am not yet sure how this could be done with the wiki.
>>>
>>> However: this raises another question:
>>>
>>> @Adobe: I assume that the Flash Player AS3 documentation will stay at the
>>> Adobe site:
>>> Do you plan to submit the Flex documentation (not just api docs) to
>>> apache?
>>> Might that include Tour De Flex?
>>> What system/format does it use?
>>> Can the community help with that?
>>>
>>> yours
>>> Martin.
>>>
>>> [1] https://chrome.google.com/**webstore/detail/**
>>> clbhjjdhmgeibgdccjfoliooccomjc**ab<https://chrome.google.com/webstore/detail/clbhjjdhmgeibgdccjfoliooccomjcab>
>>>
>>> On 11/02/2012 01:23, David Francis Buhler wrote:
>>>
>>>> I'd like to see the examples and documentation be part of an improved,
>>>> cohesive 'brand' outlined. The rest of the outline I agree with.
>>>>
>>>> Someone else had suggested the idea of emulating the
>>>> examples/documentation Sencha/JQuery use, which I second. Likewise,
>>>> Google does an excellent job with http://tour.golang.org/
>>>>
>>>> I always found Adobe to offer too many alternatives to finding
>>>> information.
>>>>
>>>> Examples:
>>>> -Adobe offered too many Flex examples in the help.adobe.com site made
>>>> accessing the information slow and painful. Future hiding of the
>>>> Examples until the user clicked a button made 'seeing' the examples
>>>> more involved.
>>>> -The Help Docs had poor SEO. Questions asked about technical problems
>>>> have a certain language, and the page-titles needed to reflect the
>>>> language developers use to search out solutions to problems.
>>>> -The Help Docs were longer than necessary.
>>>> -Tour De Flex's User Experience did not reflect how people seek out
>>>> information. It did not offer a linear evolution of 'challenges' or
>>>> 'difficulty'. Examples often error out.
>>>> -Adobe Community Help provided too many search options, that did not
>>>> reflect an understanding of how people look for information.
>>>>
>>>> -Buhler
>>>>
>>>>
>>
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Alain Ekambi <ja...@googlemail.com>.
Looks like my post did not get through ....
2012/2/10 Alain Ekambi <ja...@googlemail.com>
> We have create something similar to the EXT-GWT explorer for our product
> Gwt4Flex. ( http://www.gwt4air.appspot.com/ )
>
> Something in that direction would definitly be usefull.
>
>
>
> 2012/2/10 Martin Heidegger <mh...@leichtgewicht.at>
>
>> Hello Francis
>>
>> I think you are talking more about developer experience than end-user
>> experience.
>>
>> The wiki seems a good start for documentation to me but I agree that it
>> has some serious drawbacks.
>> For example: we can not easily include swf's and AS3 code formatting is
>> sub-par. But i think if those requests are
>> raised to the infrastructure team then they will be dealt with. This
>> would result in following documentation locations:
>>
>> *) Wiki: edited documentation, documentation about concepts with example
>> section
>> *) Blog: Time-related documentation: Changes/News
>> *) API-Docs: Generated API documentation
>>
>> It would be not so hard to provide something like the PHP Ninja manual
>> [1] that sets up on the online data.
>>
>> The only problem I see with the wiki solution is the translation. I
>> personally think "just english" is enough. However: For some reason
>> japanese developers (as a example) seem to be really trying to translate
>> everything and I am not yet sure how this could be done with the wiki.
>>
>> However: this raises another question:
>>
>> @Adobe: I assume that the Flash Player AS3 documentation will stay at the
>> Adobe site:
>> Do you plan to submit the Flex documentation (not just api docs) to
>> apache?
>> Might that include Tour De Flex?
>> What system/format does it use?
>> Can the community help with that?
>>
>> yours
>> Martin.
>>
>> [1] https://chrome.google.com/**webstore/detail/**
>> clbhjjdhmgeibgdccjfoliooccomjc**ab<https://chrome.google.com/webstore/detail/clbhjjdhmgeibgdccjfoliooccomjcab>
>>
>> On 11/02/2012 01:23, David Francis Buhler wrote:
>>
>>> I'd like to see the examples and documentation be part of an improved,
>>> cohesive 'brand' outlined. The rest of the outline I agree with.
>>>
>>> Someone else had suggested the idea of emulating the
>>> examples/documentation Sencha/JQuery use, which I second. Likewise,
>>> Google does an excellent job with http://tour.golang.org/
>>>
>>> I always found Adobe to offer too many alternatives to finding
>>> information.
>>>
>>> Examples:
>>> -Adobe offered too many Flex examples in the help.adobe.com site made
>>> accessing the information slow and painful. Future hiding of the
>>> Examples until the user clicked a button made 'seeing' the examples
>>> more involved.
>>> -The Help Docs had poor SEO. Questions asked about technical problems
>>> have a certain language, and the page-titles needed to reflect the
>>> language developers use to search out solutions to problems.
>>> -The Help Docs were longer than necessary.
>>> -Tour De Flex's User Experience did not reflect how people seek out
>>> information. It did not offer a linear evolution of 'challenges' or
>>> 'difficulty'. Examples often error out.
>>> -Adobe Community Help provided too many search options, that did not
>>> reflect an understanding of how people look for information.
>>>
>>> -Buhler
>>>
>>>
>
Re: [RT] Documentation (split from: Awesome User Experience)
Posted by Alain Ekambi <ja...@googlemail.com>.
We have create something similar to the EXT-GWT explorer for our product
Gwt4Flex. ( http://www.gwt4air.appspot.com/ )
Something in that direction would definitly be usefull.
2012/2/10 Martin Heidegger <mh...@leichtgewicht.at>
> Hello Francis
>
> I think you are talking more about developer experience than end-user
> experience.
>
> The wiki seems a good start for documentation to me but I agree that it
> has some serious drawbacks.
> For example: we can not easily include swf's and AS3 code formatting is
> sub-par. But i think if those requests are
> raised to the infrastructure team then they will be dealt with. This would
> result in following documentation locations:
>
> *) Wiki: edited documentation, documentation about concepts with example
> section
> *) Blog: Time-related documentation: Changes/News
> *) API-Docs: Generated API documentation
>
> It would be not so hard to provide something like the PHP Ninja manual [1]
> that sets up on the online data.
>
> The only problem I see with the wiki solution is the translation. I
> personally think "just english" is enough. However: For some reason
> japanese developers (as a example) seem to be really trying to translate
> everything and I am not yet sure how this could be done with the wiki.
>
> However: this raises another question:
>
> @Adobe: I assume that the Flash Player AS3 documentation will stay at the
> Adobe site:
> Do you plan to submit the Flex documentation (not just api docs) to apache?
> Might that include Tour De Flex?
> What system/format does it use?
> Can the community help with that?
>
> yours
> Martin.
>
> [1] https://chrome.google.com/**webstore/detail/**
> clbhjjdhmgeibgdccjfoliooccomjc**ab<https://chrome.google.com/webstore/detail/clbhjjdhmgeibgdccjfoliooccomjcab>
>
> On 11/02/2012 01:23, David Francis Buhler wrote:
>
>> I'd like to see the examples and documentation be part of an improved,
>> cohesive 'brand' outlined. The rest of the outline I agree with.
>>
>> Someone else had suggested the idea of emulating the
>> examples/documentation Sencha/JQuery use, which I second. Likewise,
>> Google does an excellent job with http://tour.golang.org/
>>
>> I always found Adobe to offer too many alternatives to finding
>> information.
>>
>> Examples:
>> -Adobe offered too many Flex examples in the help.adobe.com site made
>> accessing the information slow and painful. Future hiding of the
>> Examples until the user clicked a button made 'seeing' the examples
>> more involved.
>> -The Help Docs had poor SEO. Questions asked about technical problems
>> have a certain language, and the page-titles needed to reflect the
>> language developers use to search out solutions to problems.
>> -The Help Docs were longer than necessary.
>> -Tour De Flex's User Experience did not reflect how people seek out
>> information. It did not offer a linear evolution of 'challenges' or
>> 'difficulty'. Examples often error out.
>> -Adobe Community Help provided too many search options, that did not
>> reflect an understanding of how people look for information.
>>
>> -Buhler
>>
>>