Google Git
Sign in
apache / royale-docs / refs/heads/develop
commit574ca58f202de2aae6270c57629ef7b1710e1d36[log] [tgz]
authorAlex Harui <aharui@apache.org>Thu Mar 08 18:46:01 2018 -0800
committerAlex Harui <aharui@apache.org>Thu Mar 08 18:46:01 2018 -0800
treeead303a9c20a75d7936055a0d6d4044bdb9e4b40
parent07a8bb73ada025f869df746bd2cee4da45c2f757 [diff]
start tweaking the migration doc towards having emulation components
1 file changed
tree: ead303a9c20a75d7936055a0d6d4044bdb9e4b40
  1. _assets/
  2. _data/
  3. _layouts/
  4. create-an-application/
  5. data-driven/
  6. User-interface/
  7. Welcome/
  8. .gitignore
  9. _config.yml
  10. build.xml
  11. Create An Application.md
  12. Get Started.md
  13. index.md
  14. README.md
  15. royalesite.css
README.md

Apache Royale user documentation notes

Audience

We have three main audiences:

  1. Folks who have previously developed applications using Flex, and who want to learn whether and how to migrate their apps to Royale.
  2. People who are new to AS and MXML, and possibly new to developing applications altogether, and want to know how to get started.
  3. Experienced developers who want to see if Royale will give a better experience both in code development and through the application's lifecycle than what they have been using.

We can't assume that everybody understands the conversational shorthand Flex veterans use. Write for a person of good will who is reading to find out, and who wants to get to the next needed nugget of knowledge soon so they can go and make progress on the app they are working on.

Page structure

Each .md page starts with “front matter” structured like this:

---
# Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.  You may obtain a copy of the License at
# 
# http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
layout: docpage
title: README
---

Use HTML comments at the top of the document for any explanatory notes for the doc team (<!-- Not finished yet - Andrew -->) and for provenance when adapting existing material for Royale purposes (<!-- Created by Peter Ent, modified by Tom Chiverton, as part of FlexJS documentation-->).

File names and titles

  • File names do not have to be the same as the titles that display at the top of the file.
  • For file names, use all lower-case, join words with hyphens, not _ and not %20 statements, and add the markdown specification. The file name should be “important-thing.md”, not “Another%20Important%20Thing.md”, “AnotherImportantThing.md”, or “Another_important_thing.md”. This is important for SEO, human readability, and readability by assistive devices.
  • File titles should be in sentence case: “Another important Royale thing”, not “Another Important Royale Thing”. The point here is that the more capitals involved, the harder it is to read the statement.

Documentation conventions

  1. Address the reader directly, and in active voice, so “To do X, follow these steps...” rather than “When a developer wishes to do X, these steps would be followed...”
  2. Instead of “he or she” use “they” when the pronoun is for an indefinite singular actor: “When someone has an existing application to migrate, they should start by...” This offends my grammarian soul, but is becoming standard English.
  3. Link generously to other content in the help docs that may throw light on the current subject.
  4. When writing how-to material, provide the what, the so what, and the now what: what a widget is, why widgets can be important in your code, and here's how to find, adapt, or create the widget of your dreams.

Links

In the .md files, links have to be a full path without the leading slash. So to link to the published, HTML, version of /Welcome/Features/AS3.md, you would use

[AS3](Welcome/Features/AS3.html)

without the leading “/”. Links are case-sensitive, and you need to insert %20 for any space that appears in the target file's name. Check the guidance about file names, above.

When linking to locations not in the help-docs stack, including other pages in the Royale website, clicking the link should open a new browser window or tab so the reader does not lose their place in the help docs. If you want to use MarkDown, set the link like this:

[Apache Flex](http://flex.apache.org){:target='_blank'}

You can also use straight HTML for these links, like this:

<a href="http://flex.apache.org" target="_blank">Apache Flex</a>