Develop migration plan for Flex documentation

[cottage14]

There is a lot of information available about working in Flex. We should harvest what is most useful, adapt it as necessary, and make it available to Royale users.

The first step might be identifying two or three how-tos or tutorials and converting them, and then see what that shows about the work-to-benefit ratio of the conversion task.

Note: I don't see how to stick the "Documentation" tag on this issue. I would also want to assign this to myself...

[carlosrovira]

Hi Andrew, I write about this in the mailing list, but maybe is better here. I think we should start doing some migration from Apache FlexJS Wiki, for example this: https://cwiki.apache.org/confluence/display/FLEX/FlexJS+Basic+components Then we can continue looking for more stuff and work on organization. There's some work already done and we should import that adapting it a bit (changing FlexJS with Royale, and things like that) Those are for me the first steps to do About "documentation" tag I don't know, hope others could help here thanks

[piotrzarzycki21]

What do you mean by sticking documentation tag ? Do you want to have some label here ? Are you going pull requesting ?

[cottage14]

I searched for issues with the tag "documentation" and found none. I presumed therefore that such a tag exists (since github offered it) and that it might be good to tag documentation-related issues so they can be found easily. However, I don't know how to add such a tag, or even if that is the proper use for one.

On Sun, Jan 14, 2018 at 3:55 PM, Piotr Zarzycki notifications@github.com wrote:

What do you mean by sticking documentation tag ? Do you want to have some label here ? Are you going pull requesting ?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/apache/royale-asjs/issues/110#issuecomment-357537410, or mute the thread https://github.com/notifications/unsubscribe-auth/ALcS3cgNA9dibe7I7mPy-hCuayjamgQUks5tKlu7gaJpZM4RdoB5 .

-- Andrew Wetmore

http://cottage14.blogspot.com/ http://portfolio.cottage14.com http://annapolisndp.ca

[piotrzarzycki21]

We didn't have previously such issues, tagged/labeled like that. As you can see I have just tagged this issue as documentation. You can raise other one and tag them if it helps. If you will be pull requesting something each message describing pull request should have (reference #110) - ticket number.

[cottage14]

Well, this is the core of my question: are the GitHub tickets really set up to track tasks and issues related to documentation, which might not be stored and tracked the same way the code base is? There are plenty of other issue-tracking and task-tracking systems we can use for keeping up with what needs to be done regarding documentation without cluttering up the GitHub tickets, so I need guidance one way or the other.

On Sun, Jan 14, 2018 at 5:01 PM, Piotr Zarzycki notifications@github.com wrote:

We didn't have previously such issues, tagged/labeled like that. As you can see I have just tagged this issue as documentation. You can raise other one and tag them if it helps. If you will be pull requesting something each message describing pull request should have (reference #110 https://github.com/apache/royale-asjs/issues/110) - ticket number.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/apache/royale-asjs/issues/110#issuecomment-357542126, or mute the thread https://github.com/notifications/unsubscribe-auth/ALcS3a8SLzbPCB6cqap6dJDsFWNA5LdZks5tKmsugaJpZM4RdoB5 .

-- Andrew Wetmore

http://cottage14.blogspot.com/ http://portfolio.cottage14.com http://annapolisndp.ca

[piotrzarzycki21]

Right now you are helping with things on the website - We are reviewing it. If you are going to help with things royale-docs repository we may not need such tickets. I'm in favor of pull request. If you choose different path, that's ok as long as we can review it.

[cottage14]

Pull requests may work IF we are agreed on the format the pages will take. AFAICT we have not established a way of having a clickable index if we are using MarkDown pages. I am not clear how a Royale user, especially one new to the technology, would find their way through an unindexed set of pages to what they need to know.

I have built context-driven help documentation for several software firms, and in every case there was a significant amount of hands-on work in creating and curating not just the pages, but their index.

[carlosrovira]

Hi Andrew, I totally agree with that. I think we'll be creating a index and will be modeling until we get satisfied with the structure. I did something similar with the website organization and menus. And get many ideas from other similar websites (we should not try to reinvent the wheel if we can, so must see more docs and copy if we need). As you already have many experience, that's great to the get the best with this effort.

[cottage14]

Perhaps I will start by developing an index that everyone can improve until it begins to look like something we can navigate well with. I will start by refreshing my memory about the index for the Apache Flex docs...

[piotrzarzycki21]

@cottage14 by Flex docs do you mean that one? Because we have application which imitate something similar.

[carlosrovira]

Hi Piotr, don't think Andrew refer to that since is an API Reference and we are talking about a documentation guide that is more user friendly and tries to "teach" new users coming to the platform, or make more easy for existing users to solve problems.

[cottage14]

Carlos is correct. I am thinking about a structure for our documentation that helps people who are new to Royale move into using the framework with satisfaction, and that helps people who are already working with it find the helpful hint they need to solve a particular problem. Structuring our documentation so people can move through it without getting lost or disheartened

I think a good model for the sort of index we need is this one [1] for Adobe Flex. It leads you along from installing and getting started, through a quick build of a basic app, through concepts and features, and on to the complexities that an enterprise-grade application would have to deal with.

Obviously not all of this material is relevant to Royale. At the moment I am just enjoying the way the topics are organized and lead the reader forward.

I think I will start to set up a possible index in a Google Doc and open it up to comments and suggestions.

[1] https://help.adobe.com/en_US/flex/using/index.html

[carlosrovira]

Hi Andrew, I think that kind of organization id the right one. Maybe, for enhanced usability I'll maintain the left tree structure to avoid people having to go back to get the tree again. I'm looking for some Jekyll theme that can be used with gihub pages and give us this out of the box. I see that mostly all are under MIT license or AVL2, if this is ok for us we can go with that and make some configuration of the themes for us. I'll ask about this in the list explicitly to focus the work.

[cottage14]

That would be great! It is basically an iFrame with the parent appearing in the smaller part of the screen and the child files in the larger. However...we will have to make sure that plays out well on mobile devices.

[carlosrovira]

that's ok, in my search I was not taking mobile devices into account :?, I see if it works ok in that kind of screens...

[cottage14]

If we are lucky, it is a responsive-design framework and adapts to the size of the display that it detects. And if we are extra lucky, we all get ponies and ice cream.

[carlosrovira]

Hi, this one seems to match the needs :)

http://idratherbewriting.com/documentation-theme-jekyll/

but we need to wait for license question. I don't want to start nothing without license points clear to avoid future problems