Aurelia: Documentation organization discussion

[CuddleBunny]

Took a look at the docs folder because I was curious about the new direction mentioned on discourse here. The first thing that jumps out to me is the number of articles in the getting started section, currently 18. At the time of writing our main competitors have far fewer articles in their respective first doc sections:

• Angular - 5 articles
• React - 4 articles
• Vue.js - 1 article (7.5 sub-sections)

Each of these take slightly different approaches to the order in which concepts are introduced. When I see a big long list of articles under "Getting Started" I typically get concerned about the complexity right away. Therefore, as the least complex framework relative to the above, I believe we should have a less complex looking getting started section.

I like that the Angular docs have you building something simple right off the bat. I'm not really a big fan of the React docs structure, it feels like I have to follow the links rather than the outline. Vue docs are pretty good but the table of contents doesn't distinguish between hierarchy levels well at a glance which is more of a UI problem than a docs problem.

Some thoughts:

• Introduction: This article should be a separate section. It often explains the what and why of a framework. Many developers skip this section at first.

• Getting Started: This section should get you up and running with a minimal app that showcases a few basic features. A veteran developer should be able to move directly from this tutorial to the basic/advanced documentation while others may need to proceed to the tutorials section.

• Tutorials: Any other code samples structured as step-by-step learning should live here. Articles like the contact manager and dashboard app would live here. Each tutorial should have a clear goal of what domain to teach. This section can be further segmented by difficulty, perhaps expressed visually rather than by a sub-folder?

• Basic/Advanced - These two sections will contain the bulk of the documentation. I believe the distinction here should be based on how frequently a feature will be used rather than its actual complexity.

• Examples - This section will house code samples that aren't structured as step-by-step learning. Each example should however still have a clear explanation of the sample's goals, architecture, and the features that it is intended to showcase.

• Community and resources sections are fine as-is.

Ultimately this is all speculation and biased opinion. A better approach would be to test focus groups on mockups and do stuff like A/B testing for bounce rate but the effort involved in that doesn't make it practical for a day 0 release. I personally believe that the documentation will be one of, if the the most critical elements of the vNext general release. Hopefully this, in combination with other feedback like #522, will help this version launch a huge success.

[EisenbergEffect]

Adding our technical writer @StevenHiggs24 to provide some feedback based on his experience. I think he was against using terms like "basic" and "advanced" and felt that "Getting Started" was appropriate for a full section of the docs (rather than just a single tutorial).

[StevenHiggs24]

Actually, my suggestions were similar to many of Josh's suggestions.

These were my suggestions:

1. "Foundations" could be named "Getting Started". As mentioned in the description for 'Foundations', this section should contain everything a new user would need to get up and running as quickly as possible.

2. If possible, I think it would also be helpful to have a topic inside the "Getting Started" section called something like "Quick Start Guide". It would be one topic that provides all the step by step instructions that a new user must or should do to quickly get to point where they are set up and using the product to develop their app. This topic could have links to other topics within this section (or other sections), but it would be a one-stop instructional tutorial that would cover all the basics of a typical workflow for a new user to go from purchasing the product to functionally using it. However, this type of "Quick Start Guide" is usually only possible if there is a typical, linear workflow. If there are a lot of different ways to achieve this or it depends on what they want to do, maybe it's not possible. Just a suggestion in case this is possible.

3. "Essentials" could be named "Basic Customization" or "Basics for Building an App", or something similar. It would include the most common and simple types of activities.

4. "Mastery" could be named "Advanced Customization". This would make it clear that this section only includes topics for advanced users.

5. "API Reference" is good. Everyone knows what that means.

6. "Recipes" could be named "Code Examples" or something similar. It seemed that this is what is meant by "Recipes". Maybe hipster coders know what is meant by this word in this community, but it may not be clear to others. They might think: Is it a list of pre-defined scripts that can be combined to create an app? Is it a list of components or snippets that can be combined? Is it a set of instructions or tutorials? Etc. Etc. Etc. I think something like "Code Examples" makes it very clear what they would find here.

7. "Contributing" could be named "Community Contributions". This is just a suggestion to make it very clear that this section includes information about them (the community) making contributions to the project.

8. "FAQ" should be a topic by itself or a section by itself. It could be a single topic that has a growing list of questions along with the answers/solutions. It could also be its own section and each topic within the section would be posed as a question and offer the answer/solution. Personally, I think one topic is best, but either is fine.

9. The rest of the topics within that section (currently "FAQ") could be in a section named "Other Resources" or just "Resources".

---

Comments on Josh's suggestions:

• Having a separate "Introduction" article in its own section is a good idea.

• I agree that the "Getting Started" shouldn't have a ton of articles. The very basic information devs need to get up and running, and as I suggested, a "Quick Start Guide" would be helpful in this section.

• I personally think the tutorials should go in the "Basic Customization" and "Advanced Customization" sections and I agree that these sections should contain most of the articles.

[EisenbergEffect]

Thanks @StevenHiggs24. You may not have reviewed the docs again since we last discussed, but I previously made the following changes:

• "Foundations" was renamed to "Getting Started"
• There is the equivalent of a quick start guide inside of "Getting Started". However, it's named "Building a Todo App". I will rename it to "Quickstart Guide" today.
• "Essentials" was renamed to "App Basics"
• "Mastery" was renamed to "Advanced Scenarios" (customization doesn't really make sense in this context)
• "Recipes" was renamed to "Examples"
• "Contributing" was renamed to "Community Contributions"
• "FAQ" was made into its own article
• A "Resources" group was created, which includes the "FAQ", as well as other articles.
• There is already a dedicated "Introduction" article.

The biggest issue to resolve is the number of topics in the "Getting Started" section and how to re-organize that content. I can slim down the topics in that group, and would recommend the following:

• Introduction
• Quickstart Guide
• Components
• Displaying Basic Data
• Working with Collections
• Conditional Rendering
• Handling Events

However, that leaves 11 topics with no home. If we move them to App Basics, then we will have 24 topics in that section. So, how should we handle this? Just have a large Basics section? Rename basics to "Intermediate" and put the other articles in a new "Basics" section? Something else?

[StevenHiggs24]

@EisenbergEffect Yeah. I saw the changes. I just wanted Josh to see what I originally suggested.

In terms of the 11 topics, I personally don't see a problem with there being 24 (or whatever) topics in the App Basics section. I suppose another option would be to add another section called "Tutorials" that would hold both basic and advanced tutorials, but that only makes sense if there will be a very clear distinction between the tutorial topics and the other topics in the App Basics and Advanced Scenarios sections.

[EisenbergEffect]

Cool. There are only a few true tutorials. Probably not enough for a full section. If no one sees an issue with there being 24 topics in the basics section, I can re-arrange things as above probably today or tomorrow. I'm definitely happier with the slimmed down getting started content. I'd love to hear what @CuddleBunny thinks.

[jwx]

I've talked about how much I like Quick starts, but I'd like to emphasize that it's not only for the "first contact" but for more or less everything. Use a progressive approach and start with little code and few details and then expands from there. Basically start _everything_ with a TL;DR and then go into details and less frequent usages.

One of the best things with Aurelia is how you can do a lot more with a lot less (and cleaner) code. So when showing code and describing functionality, start with maximum convention and as little code, and description, as possible and then gradually add details to it. The sooner someone can be done with a specific doc because they found their use case the better. People interested in the gritty details will stick around and read them regardless of whether they are first or last.

[EisenbergEffect]

Every article will have a section at the top for "Here's what you'll learn..." which is basically your tldr idea. We can make some changes to start with conventions. It's been odd because those haven't existed until recently in vNext, and they require a specific build setup. So, for example, if we want our Quickstart Guide to use the script tag version of Aurelia, we can't use conventions at all. Maybe we want to introduce @3cp makes tool right from the beginning of the quick start. That makes a nice path for conventions and is easy to setup npx makes aurelia but does require that they have Node.js installed. If we go that route, then we might need an alternate quick start for the script tag only setup as well. These are the reasons I haven't written the quickstart or introduction yet, but skipped ahead to writing the last 5 topics.

What are your thoughts?

[CuddleBunny]

I am also okay with tossing everything into the next section. I don't think there can really be too much there, but perhaps time will tell. I like having a separate tutorials section even if there are few articles just because it might not necessarily be what a user is looking for in the basics/advanced sections. I expect just cold hard information there with a little explanation. That said, it isn't really a method for slimming down those sections because any topic covered in a tutorial should be covered there separately. This will reduce cases like with the current docs where some features simply go unnoticed.

[jwx]

The less they have to do in Quickstart the better, but installing Node.js might be necessary if the script tag setup doesn't support conventions. For things like this, I like linked or expandable content. For example:

First of all, make sure you've got Node.js version X or later installed

What is Node.js and how do I install it?

Node.js is a program that will make it possible to run the Aurelia tools from the command line on your computer (or whatever the appropriate description is). You'll need at least version X and it can be installed from here.

With Node.js installed, open a command line and run
npx makes aurelia

_And so on..._

Here is another example that uses expandable content to make the document easier to skim.

[EisenbergEffect]

All above recommendations for naming and organization have been applied to master. Thanks everyone for the feedback!