RFC: Documentation Content and Organization

[mauerbac]

We need your help to provide specific feedback around our documentation content and structure. We would appreciate it if you would take three-to-five minutes to provide your thoughts in the comments.

The below questions are provided to guide your response:

1. Does the Amplify documentation provide clear paths to the information you are seeking, and how can we improve it?
2. Once located, is the content sufficient to meet your needs or what are the gaps?
3. Is the Amplify documentation easy to read or too verbose?

[joec58]

I have yet to find an actual API reference for Amplify's java libraries. There is an API Reference link at the top of the home page but that goes to, what appears to be, the AWS SDK java libraries. There was no mention of Amplify.

I tried to run javadoc on the master Amplify java code downloaded from github but it didn't work for me.

[StephenBlank]

From the perspective someone with relatively little experience with Amplify:

Does the Amplify documentation provide clear paths to the information you are seeking, and how can we improve it? Yes. Information is easy to find and the getting started tutorials work well. Next steps and related articles at the end of the documents are relevant and nice to have. For improvement, add interactive code and guides when possible.

Once located, is the content sufficient to meet your needs or what are the gaps? My team found that the getting started guides work well for the most part. It is difficult to fill every single gap. For instance, we used this document to try to enable cloud sync for DataStore. We couldn't get our local changes to show up in the backend and we were not sure if the sync was supposed to happen automatically or if we were missing a line of code somewhere. It turned out to be an issue with our schema. But the document never says anything like "after you pushing the backend to the cloud, Datastore will start syncing automatically." Very niche case, but it took us a while to finally try with a simpler schema.

Is the Amplify documentation easy to read or too verbose? Not verbose enough. Explain things like we are five. It is easy to forget the perspective of a complete beginner.

[nubpro]

More advance usecases on how to use DataStore

https://github.com/aws-amplify/docs/issues/3150

[tchalvak]

1. It’s easy to find the documentation sections, whether through navigation or through google search.
2. The thoroughness of the documentation often leaves something to be desired, usually in the area of authentication for the react libraries. You can build anything you want that’s visual only, but the moment you go further, you need an authentication system around it, and there the docs fall down. I am often hitting the authentication scenarios and bouncing off as they don’t contain everything I need to get started fast (eg with the hosted UI approach).
3. Documentation is easy to read and understandable when present.

Overall, I feel like a documenter needs to run through a few “early site setup with auth and data behind authentication” react apps a few times and fill in the gaps.

[markramrattan]

1. Does the Amplify documentation provide clear paths to the information you are seeking, and how can we improve it?

I would prefer the main navigation bar (Pic 1) was on the main first page. Rather than clicking getting started. Faster pathway to the content (for me). I wasn’t sure the block navigation on the main page was actually navigation or just cards displaying brief summaries of the different areas of content. I think the common navigation route would be more intuitive.

Pic 1: 

2. Once located, is the content sufficient to meet your needs or what are the gaps?

I would really love full working / real examples (on github) for each area being discussed. I know maintaining that would be a nightmare. Maybe interlink the examples with trusted AWS Heroes / Developers who are showing a history of keeping the content up to date. Then review monthly to keep or drop the links.

I normally copy parts of the examples on the docs and search github to find out which repositories are using that example. Then learning how they implemented it and then how I could do the same within my project.

3. Is the Amplify documentation easy to read or too verbose?

I think its broken down well in manageable chunks / sections. For example API (GraphQL) -> Create, Update, Delete data is separated from Fetch data etc. Makes it easier to find a particular area. Maybe add the medium feature of this is a 5min read would help. I need to spend more time reading through the docs. If I know the approx, can block out time during lunch to cover a particular area.

[swaminator]

@markramrattan @nubpro @tchalvak one hypothesis we have is that it is difficult for new users who land on the Amplify docs to understand what Amplify is (given the different offerings we have). Right now we've sectioned it by our tools. Was wondering if you can share your opinions on if that approach works well? Is it beneficial to goto CLI docs to learn about (e.g. data modeling) and then head back to the Library docs(e.g. to learn about datastore) or would you rather see a "Data" topic that covers all the capabilities Amplify offers.

[rberger]

The docs are nice when getting started, but I find them difficult to use as reference after I've gotten past the first time usage. In particular would be nice to have Reference docs for the APIs and CLI for quick lookup of what's available, what are the options/parameters for each item. Bonus points for links to more detailed tutorials in-depth usage examples.

[sstiglitz]

I agree with @rberger. I am constantly referring back to the docs, usually by typing docs.amplify.aws in the url. The main page is a landing page and the main navigation, which is visible virtually everywhere else, is absent. Most of the users are going to be devs looking for info very quickly. I suggest limit the amount of clicks and put the user right in front of the content with a consistent and comprehensive navigation off to the side. I think Material-UI is a good example

Focusing on the content is important, but I feel there are some UI/UX improvements that can be made to better navigate the docs site. For example, each of the tabs in the main navigation feels disjoint and there are subtle layout differences. I feel consolidating the nav into a consistent layout would go a long way in remembering where thing are within the docs site.

[markramrattan]

Right now we've sectioned it by our tools. Was wondering if you can share your opinions on if that approach works well? Is it beneficial to goto CLI docs to learn about (e.g. data modeling) and then head back to the Library docs(e.g. to learn about datastore) or would you rather see a "Data" topic that covers all the capabilities Amplify offers.

@swaminator I like and prefer the sectioning by tools. Makes you align with the pathway you've chosen. Even if it's a mix, if you're trying to solve an issue I would go to the relevant area and dig further. If you went the other way with 'Data' being the topic and that covers the different tools within, you'd be seeing content not relevant to what you want (depending on how the info is displayed).

Also, have you seen those AWS Hands-on Labs & Challenges on Cloud Academy? (Hands-on learning and troubleshooting challenges). I think those for Amplify would be epic (if integrated and aligned within the Amplify docs). You would also have more metrics to see what people are succeeding at & areas where alternative types of support (workshops / blogs) are needed within the docs.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.