You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by OK <po...@olafkrueger.net> on 2016/09/09 05:08:42 UTC
[FlexJS] Starting with the Docs
Hi,
I notice everyone agrees that the docs are crucial, so why not just starting
with it instead of wasting time with discussion? ;-)
Some thoughts to the wiki:
It is also not my favorite candidate for the docs cause it feels a bit
old-fashioned and I'm always lost while searching for something.
But the wiki is there and we could just start with it. Maybe the wiki could
be modernized or the content could be transfered to whatever hip platform
some day.
For the moment I would say "content first" should be the motto!
Suggested roadmap:
- Extract all component names (strands and beads?)
- Create empty wiki pages and name it with the particular component name
- Create one example/reference documentation using a simple component
- Discuss the example and fine tune it
- Complete all the other docs with the reference as template
I think just to have a list of all available components (with empty docs)
would be a progress.
Though my FlexJS skills are very low and my english is bad I'd try to start
with the first point.
But there're some questions:
1) Where the componets located? Could there be easily extracted manually
from the reop?
2) What is a component in FlexJS? Is it a strand or a bead, or both?
3) Are beads interchangeable through any strand?
Thanks,
Olaf
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FlexJS] Starting with the Docs
Posted by OK <po...@olafkrueger.net>.
>3) Are beads interchangeable through any strand?
I thought I should share my thoughts on this:
I wonder if we should separate strands and beads so that they exist side by
side iside the docs or if we should nest beads under the related strand?
If some beads would be interchangable and some not we have to think about
the docs structure a bit more.
You see I've no idea of FlexJS... but starting with the docs could change
this ;-)
Thanks,
Olaf
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55007.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
AW: [FlexJS] Starting with the Docs
Posted by Christofer Dutz <ch...@c-ware.de>.
Hi Alex,
actually that's not quite true. We have the Wiki and the Website. The problem is that usually changing the website is far more work than to edit the wiki. The thing with the Maven Site generation however is that it automatically generates the entire Project documentation AND automatically updates the content in Subversion. All is prepared to start doing this, but I disabled the final upload of the generated site as we haven't discussed that yet and I didn't want to do it without. Even if linking to ASDoc on the Flex Buildserver works, the server isn't really great from a performance point of view. Having the documentation on the main Apache Webservers would definitely be nicer.
Have you guys had a look at the links I provided? The cool thing with them is that they are absolutely standard and anyone will know where to look for what information. Every maven-based projects has the same.
Chris
________________________________
Von: Alex Harui <ah...@adobe.com>
Gesendet: Samstag, 10. September 2016 07:12:31
An: dev@flex.apache.org
Betreff: Re: [FlexJS] Starting with the Docs
On 9/9/16, 12:19 PM, "Nemi" <ne...@gmail.com> wrote:
>As from my perspective as Flex SDK user, current wiki is like unorganized
>book. And it has info for sdk-developers and for sdk-users, which IMHO,
>must
>be always separated.
>
>For a start, I think docs should be on some nice named location like:
>http://flex.apache.org/flexjs/docs
Eventually we will get away from the wiki, but it is all we have for now
until we decide how to do the future doc. Wiki does allow comments. I
added an HTTP redirect so your url ends up at the FlexJS section of the
wiki (for now).
I also added the FlexJS ASDoc to the Documentation menu. It goes to the
CI server (apacheflexbuild) because copying ASDoc in the current CMS is
painful, and I'd rather show a live version for now in hopes that new
contributors will help improve the doc and will be able to see their
improvements in the nightly build without requiring someone to use the
CMS. For some reason the FlexJS ASDoc has two title-bars. Volunteers are
welcome to help debug that.
Thanks,
-Alex
Re: [FlexJS] Starting with the Docs
Posted by Alex Harui <ah...@adobe.com>.
On 9/9/16, 12:19 PM, "Nemi" <ne...@gmail.com> wrote:
>As from my perspective as Flex SDK user, current wiki is like unorganized
>book. And it has info for sdk-developers and for sdk-users, which IMHO,
>must
>be always separated.
>
>For a start, I think docs should be on some nice named location like:
>http://flex.apache.org/flexjs/docs
Eventually we will get away from the wiki, but it is all we have for now
until we decide how to do the future doc. Wiki does allow comments. I
added an HTTP redirect so your url ends up at the FlexJS section of the
wiki (for now).
I also added the FlexJS ASDoc to the Documentation menu. It goes to the
CI server (apacheflexbuild) because copying ASDoc in the current CMS is
painful, and I'd rather show a live version for now in hopes that new
contributors will help improve the doc and will be able to see their
improvements in the nightly build without requiring someone to use the
CMS. For some reason the FlexJS ASDoc has two title-bars. Volunteers are
welcome to help debug that.
Thanks,
-Alex
Re: AW: AW: [FlexJS] Starting with the Docs
Posted by Nemi <ne...@gmail.com>.
About comments option, of course it is more work, but just saying, IMHO it
will give very easy way for community to add code use examples, snippets
related to topic, report error in docs, suggest docs improvement, ask
question.. etc
Hm maybe something like PHP has "User Contributed Notes".
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55261.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FlexJS] Starting with the Docs
Posted by Nemi <ne...@gmail.com>.
As from my perspective as Flex SDK user, current wiki is like unorganized
book. And it has info for sdk-developers and for sdk-users, which IMHO, must
be always separated.
For a start, I think docs should be on some nice named location like:
http://flex.apache.org/flexjs/docs
I would really dig deeper in FlexJS if there are clean docs. And especially,
Flex vs FlexJS differences document with infographics. Then, for example, I
would know how to do my refactorings more in a way that is easier for me to
move on to FlexJS some time later.
Maybe for some later time, it would be great if docs pages would have
comments available.
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55033.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
AW: [FlexJS] Starting with the Docs
Posted by Christofer Dutz <ch...@c-ware.de>.
If you are getting a tomcat error page, probably Jenkins is currently running a build and had cleaned up the workspaces target directory. In that case, just wait for the build job to finish.
Chris
________________________________
Von: Christofer Dutz <ch...@c-ware.de>
Gesendet: Freitag, 9. September 2016 10:26:45
An: dev@flex.apache.org
Betreff: AW: [FlexJS] Starting with the Docs
Just an idea of how we could eventually make writing the documentation a little easier and keep flexible regarding the used CMS.
I use Asciidoctor for writing documentation. It's the same markup you use on Github to auto-render these nice looking sites. The good thing would be that we can continue to use the infra that we have.
I already added support for this in falcon also some example files in "src/site/asciidoc".
The cool thing with this option is that maven supports auto-updating the project site with the latest content AND you have the documentation in the same place as you have the code. It automatically produces a project website together with the JavaDoc and all the other project reports.
To try it out, just go to the falcon repo and run "mvn site:site" (Alternatively "mvn site"). This will produce a directory "target/site"
You can also have a look at the output it creates at [1]. In order to access that url you have to login to jenkins using your normal apache credentials.
The pages "Building from source" and "Build structure" are generated from the two asciidoctor files.
Please give it a try. I think we should start going down that path for documentation, but that's just my opinion.
Chris
[1]: https://builds.apache.org/view/E-G/view/Flex/job/FlexJS%20Compiler%20(maven)/ws/target/site/index.html
________________________________
Von: OK <po...@olafkrueger.net>
Gesendet: Freitag, 9. September 2016 08:59:05
An: dev@flex.apache.org
Betreff: Re: [FlexJS] Starting with the Docs
Alex Harui wrote
> Depending on how you look at it, each class is a component, or maybe only
> classes listed in manifest.xml files are components.
> You might get a directory listing or parse the manifest files.
> I've been tempted to find a way to mark or annotate classes as being
> intended for application developers as opposed to framework developers.
I've just browsed through the asjs repo and it seems to me that it is
already a challenge to get list
of the relevant classes/components.
I've found e.g. [1] wich is probably a summary of the core components.
Would that be the way to search for this file inside each "component set" to
get an overview of all components?
Alex Harui wrote
> I'm still hoping we can be more efficient about the doc. If we know there
> is going to be a Tour de FlexJS, we should put the examples in there as
> opposed to having examples in both places, and link back and forth between
> the doc and Tour de FlexJS, and probably the ASDoc as well.
Maybe the wiki is not the best place to start with the docs...
What do you think of using github?
We could start with a repo that contains examples for the particular
components and maybe this could be consumend by an "Tour de FlexJS" app
using the github API?
Thanks,
Olaf
[1]
https://github.com/apache/flex-asjs/blob/develop/frameworks/projects/Core/src/main/resources/basic-manifest.xml
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55012.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: AW: [FlexJS] Starting with the Docs
Posted by Alex Harui <ah...@adobe.com>.
If we know we want a Tour de FlexJS, one plan would be to create a Git
repo for it and recruit volunteers to start migrating Tour de Flex to this
new repo. Then we'd learn what to put in our migration document as well.
Thoughts?
-Alex
On 9/9/16, 2:49 AM, "OK" <po...@olafkrueger.net> wrote:
>Christofer Dutz wrote
>> You can also have a look at the output it creates at [1]
>
>Looks very promising to me!
>
>What would be the steps to achive a FlexJS component documentation using
>this technique?
>Probably we have to place one of these Asciidoc files for each relevant
>strand and bead?
>Would the component docs be part of the existing site build or inside its
>own shell.
>Would it be possible to include ASdocs with some magic?
>
>Only to consider another option:
>I just realize that the flex asdoc [1] are part of Apache.
>Are there also tools available to build this also nice documentation?
>
>Olaf
>
>[1] https://flex.apache.org/asdoc/
>
>Olaf
>
>
>
>--
>View this message in context:
>http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-
>the-Docs-tp55005p55016.html
>Sent from the Apache Flex Development mailing list archive at Nabble.com.
AW: AW: [FlexJS] Starting with the Docs
Posted by Christofer Dutz <ch...@c-ware.de>.
Hi Olaf,
Asdoc integration is on my to-do list. But for this we need to port/add the asdoc support to falcon. An alternative would be to use the old flex version, but we would need to publish the jar(s) to Maven central somehow.
Chris
Von meinem Samsung Galaxy Smartphone gesendet.
-------- Ursprüngliche Nachricht --------
Von: OK <po...@olafkrueger.net>
Datum: 09.09.16 11:52 (GMT+01:00)
An: dev@flex.apache.org
Betreff: Re: AW: [FlexJS] Starting with the Docs
Christofer Dutz wrote
> You can also have a look at the output it creates at [1]
Looks very promising to me!
What would be the steps to achive a FlexJS component documentation using
this technique?
Probably we have to place one of these Asciidoc files for each relevant
strand and bead?
Would the component docs be part of the existing site build or inside its
own shell.
Would it be possible to include ASdocs with some magic?
Only to consider another option:
I just realize that the flex asdoc [1] are part of Apache.
Are there also tools available to build this also nice documentation?
Olaf
[1] https://flex.apache.org/asdoc/
Olaf
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55016.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: AW: [FlexJS] Starting with the Docs
Posted by OK <po...@olafkrueger.net>.
Christofer Dutz wrote
> You can also have a look at the output it creates at [1]
Looks very promising to me!
What would be the steps to achive a FlexJS component documentation using
this technique?
Probably we have to place one of these Asciidoc files for each relevant
strand and bead?
Would the component docs be part of the existing site build or inside its
own shell.
Would it be possible to include ASdocs with some magic?
Only to consider another option:
I just realize that the flex asdoc [1] are part of Apache.
Are there also tools available to build this also nice documentation?
Olaf
[1] https://flex.apache.org/asdoc/
Olaf
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55016.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
AW: [FlexJS] Starting with the Docs
Posted by Christofer Dutz <ch...@c-ware.de>.
Just an idea of how we could eventually make writing the documentation a little easier and keep flexible regarding the used CMS.
I use Asciidoctor for writing documentation. It's the same markup you use on Github to auto-render these nice looking sites. The good thing would be that we can continue to use the infra that we have.
I already added support for this in falcon also some example files in "src/site/asciidoc".
The cool thing with this option is that maven supports auto-updating the project site with the latest content AND you have the documentation in the same place as you have the code. It automatically produces a project website together with the JavaDoc and all the other project reports.
To try it out, just go to the falcon repo and run "mvn site:site" (Alternatively "mvn site"). This will produce a directory "target/site"
You can also have a look at the output it creates at [1]. In order to access that url you have to login to jenkins using your normal apache credentials.
The pages "Building from source" and "Build structure" are generated from the two asciidoctor files.
Please give it a try. I think we should start going down that path for documentation, but that's just my opinion.
Chris
[1]: https://builds.apache.org/view/E-G/view/Flex/job/FlexJS%20Compiler%20(maven)/ws/target/site/index.html
________________________________
Von: OK <po...@olafkrueger.net>
Gesendet: Freitag, 9. September 2016 08:59:05
An: dev@flex.apache.org
Betreff: Re: [FlexJS] Starting with the Docs
Alex Harui wrote
> Depending on how you look at it, each class is a component, or maybe only
> classes listed in manifest.xml files are components.
> You might get a directory listing or parse the manifest files.
> I've been tempted to find a way to mark or annotate classes as being
> intended for application developers as opposed to framework developers.
I've just browsed through the asjs repo and it seems to me that it is
already a challenge to get list
of the relevant classes/components.
I've found e.g. [1] wich is probably a summary of the core components.
Would that be the way to search for this file inside each "component set" to
get an overview of all components?
Alex Harui wrote
> I'm still hoping we can be more efficient about the doc. If we know there
> is going to be a Tour de FlexJS, we should put the examples in there as
> opposed to having examples in both places, and link back and forth between
> the doc and Tour de FlexJS, and probably the ASDoc as well.
Maybe the wiki is not the best place to start with the docs...
What do you think of using github?
We could start with a repo that contains examples for the particular
components and maybe this could be consumend by an "Tour de FlexJS" app
using the github API?
Thanks,
Olaf
[1]
https://github.com/apache/flex-asjs/blob/develop/frameworks/projects/Core/src/main/resources/basic-manifest.xml
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55012.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FlexJS] Starting with the Docs
Posted by OK <po...@olafkrueger.net>.
Alex Harui wrote
> Depending on how you look at it, each class is a component, or maybe only
> classes listed in manifest.xml files are components.
> You might get a directory listing or parse the manifest files.
> I've been tempted to find a way to mark or annotate classes as being
> intended for application developers as opposed to framework developers.
I've just browsed through the asjs repo and it seems to me that it is
already a challenge to get list
of the relevant classes/components.
I've found e.g. [1] wich is probably a summary of the core components.
Would that be the way to search for this file inside each "component set" to
get an overview of all components?
Alex Harui wrote
> I'm still hoping we can be more efficient about the doc. If we know there
> is going to be a Tour de FlexJS, we should put the examples in there as
> opposed to having examples in both places, and link back and forth between
> the doc and Tour de FlexJS, and probably the ASDoc as well.
Maybe the wiki is not the best place to start with the docs...
What do you think of using github?
We could start with a repo that contains examples for the particular
components and maybe this could be consumend by an "Tour de FlexJS" app
using the github API?
Thanks,
Olaf
[1]
https://github.com/apache/flex-asjs/blob/develop/frameworks/projects/Core/src/main/resources/basic-manifest.xml
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55012.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FlexJS] Starting with the Docs
Posted by Alex Harui <ah...@adobe.com>.
On 9/8/16, 10:08 PM, "OK" <po...@olafkrueger.net> wrote:
>Hi,
>I notice everyone agrees that the docs are crucial, so why not just
>starting
>with it instead of wasting time with discussion? ;-)
>
>Some thoughts to the wiki:
>It is also not my favorite candidate for the docs cause it feels a bit
>old-fashioned and I'm always lost while searching for something.
>But the wiki is there and we could just start with it. Maybe the wiki
>could
>be modernized or the content could be transfered to whatever hip platform
>some day.
>
>For the moment I would say "content first" should be the motto!
>
>Suggested roadmap:
>- Extract all component names (strands and beads?)
>- Create empty wiki pages and name it with the particular component name
>- Create one example/reference documentation using a simple component
>- Discuss the example and fine tune it
>- Complete all the other docs with the reference as template
>
>I think just to have a list of all available components (with empty docs)
>would be a progress.
>Though my FlexJS skills are very low and my english is bad I'd try to
>start
>with the first point.
>But there're some questions:
>
>1) Where the componets located? Could there be easily extracted manually
>from the reop?
Depending on how you look at it, each class is a component, or maybe only
classes listed in manifest.xml files are components.
You might get a directory listing or parse the manifest files.
>2) What is a component in FlexJS? Is it a strand or a bead, or both?
See above.
I've been tempted to find a way to mark or annotate classes as being
intended for application developers as opposed to framework developers.
>3) Are beads interchangeable through any strand?
Most beads are re-usable, but not necessarily to any other strand.
I'm still hoping we can be more efficient about the doc. If we know there
is going to be a Tour de FlexJS, we should put the examples in there as
opposed to having examples in both places, and link back and forth between
the doc and Tour de FlexJS, and probably the ASDoc as well.
HTH,
-Alex