Thanks Josh, more specific information like this is helpful because it narrows down what is missing. We should make the ASDoc more readily available.
Adobe had a whole team dedicated to documentation. Apache Flex does not have that, so we need to be smarter about how to make our doc better. Just at random, I picked AreaChart from the Adobe Flex SDK ASDoc. On the main page for AreaChart there is an anchor-link to the bottom where there is a simple example, plus links to many pages of examples. And elsewhere, there is Tour De Flex. There is no way our current set of volunteers, even if we stopped working on bug fixes and other missing features, could somehow reproduce the equivalent documentation to match what Flex has even in a year, so I'm wondering if folks think it would be better to just start on a Tour De FlexJS and have the ASDoc point there, so there aren't examples in 3 different places like Flex has. That would certainly save us time, but would it be sufficient? And do others have the time to pitch in on building out a Tour De FlexJS? Thanks, -Alex On 9/8/16, 8:55 AM, "Josh Tynjala" <joshtynj...@gmail.com> wrote: >There really is a need for some better basic documentation. Not even >advanced level stuff. We already have some of that, actually. Most users >aren't going to start developing custom components and contributing right >away, though. They're going to want some more hand holding. > >Let's say that I went to this section about FlexJS on the wiki: > >https://cwiki.apache.org/confluence/display/FLEX/FlexJS > >I'm looking for a list of available components, and hopefully, each >component has a page with the simplest example possible of how to use it. >I >just clicked around on a few sub-pages, and I couldn't find anything like >that. Does it exist? I don't know, but after a couple of minutes of >looking, a potential new user just gave up because FlexJS looks too hard >to >learn. > >I also went to the main website to look for the API reference (asdocs) for >FlexJS: > >http://flex.apache.org/ > >There's nothing under the documentation menu. I only found Flex and >FlexUnit asdocs. Based on their URLs, I took a random guess that this >might >work, but no luck: http://flex.apache.org/flexjs/asdoc/ > >That's about as much as the average potential new users is going to try >before giving up. They're probably not even going to install FlexJS and >look at the included examples. There wasn't enough information on the >website to make them want to bother. > >I guarantee you, if the wiki lists all of the components with ridiculously >simple examples, and if we post some FlexJS asdocs under the documentation >menu on the main site, that's going to make a huge difference. > >- Josh > >On Thu, Sep 8, 2016 at 8:31 AM, Christofer Dutz ><christofer.d...@c-ware.de> >wrote: > >> I don't quite agree. >> >> >> The problem with FlexJS is that you have to do things differently than >> with Flex. For Flex the web is full of useful and less useful how-tos on >> the topic, but for FlexJS there is next to nothing to be found. >> >> >> It would be great to have some Documentation, walking an interested User >> into the details and concepts of FlexJS. Without a "handbook" we have >>some >> kick-ass software only kick-ass users will understand to use. I doubt >>that >> targeting only the kick-ass users will bring us the user-numbers we are >> looking for. It's not "features over all". The more we do without >> documenting, the more documentation-debt we produce. >> >> >> I tried writing documentation for the parts I do, while I'm at it. I >>hope >> I was doing a somewhat good job of this, and I think it would be great >>to >> not only code concepts but write down some words about them in the Wiki. >> >> >> Perhaps we should start a wiki page, containing features we consider >> important for a 1.0.0 and could add a dedicated docs-wish list. Jira >>sort >> of doesn't cleanly support creating and prioritizing a big-picture. >> >> >> Chris >> >> ________________________________ >> Von: Alex Harui <aha...@adobe.com> >> Gesendet: Donnerstag, 8. September 2016 17:16:03 >> An: dev@flex.apache.org >> Betreff: Re: FlexJS - roadmap to 1.0 release >> >> What kind of documentation are you talking about? Just filling out >>ASDoc, >> or pages of words? >> >> There are so many things that need to be done that having folks who >>aren't >> currently committing code to FlexJS help with filling out ASDoc and >> recruiting people who are good at writing to write more verbose >> documentation would be a great help. I don't agree that doc is more >> important than functionality until you have enough functionality, and >>the >> lack of a testimonial makes me think we aren't quite there yet. >> >> If someone tried FlexJS and isn't sure what they can do, a more specific >> question/comment would help. We could create a JIRA issue called >>"FlexJS >> Doc Wish list" and folks can comment in there. We can't guess what >>folks >> need. It would be better for folks to try to do what they want to do and >> if it can't do it, they should ask about it. >> >> Thanks, >> -Alex >> >> On 9/8/16, 12:18 AM, "Harbs" <harbs.li...@gmail.com> wrote: >> >> >+1000 >> > >> >Documentation is the first thing people look for in a framework. This >>is >> >absolutely critical (more than functionality and production apps). >> >Unfortunately, I’m really bad at documentation, so I can’t help much >>with >> >this. >> > >> >AFA productions apps go, my conversion to FlexJS is moving along quite >> >nicely. I don’t have an ETA yet, but I’m really hoping it will be >>usable >> >by the end of the year (and hopefully sooner). >> > >> >On Sep 8, 2016, at 9:27 AM, piotrz <piotrzarzyck...@gmail.com> wrote: >> > >> >> In my opinion documentation is the second thing which need to be done >> >>before >> >> 1.0 >> > >> >>
