RFC: Top 3 documentation problems to solve

[jakeburden]

This is a Request For Comments (RFC). RFCs are intended to elicit feedback regarding a proposed change to the Amplify Framework. Please feel free to post comments or questions here.

This an RFC to identify the top 3 problems you'd like us to solve in regards to documentation and the docs site itself.

You can link to the relevant issue or PR, or just describe the problem. It can be an issue already in flight or something brand new. It's your top 3.

[aspittel]

1) An information architecture that leads to better navigation. Right now, it's difficult to find the needed information because of the CLI/Console/Libraries/Guides silo-ing. Topic categorization that's aggregated to one place would be awesome.

2) More clear and upfront explanation on what Amplify is. Who is it for, what can it be used for, and what are the different aspects of it. Visual diagrams would be great here, and the getting started home page should be more visually enticing.

3) More clear feedback mechanisms and better metrics tracking: what is working for customers and is helping them, what are they not able to find. Writing a github issue is high friction: it takes a lot of work. A thumbs up/thumbs down with option for more feedback would be quicker. In addition, adding more analytics around if the code snippets are being used would be great.

[renebrandel]

I agree with @aspittel on 1 and 2.

On 2 would be cool to have our two main getting started experiences listed:

My 3rd pick would be F_A_N_T_A_S_T_I_C search. Finding the right content faster can be vastly improved.

[aspittel]

Agreed @renebrandel, and the search should better filter by the technology you're in too. i.e. only JS results should be shown if you're in the JS docs.

[markramrattan]

1. I find it difficult piecing together all the information I need from the Amplify documentation to create a fully working product (mobile application). I would love for there to be amplify workshops embedded (improving the getting started section with deeper examples) in the documentation. Rather than separated with external links: https://amplify.aws/community/resources

2. I've done many of the Amplify tutorials but end up frustrated with not knowing the next part and I end up looking on YouTube for solutions (not the documentation). That leads me to different solutions for i.e. Todo App: https://youtu.be/N8kYlimhuLw (questioning how it relates to the documentation). Would be good to have official videos alongside the getting started or different areas of the documentation. That cover it end to end. Like one of Kilo's tutorials: https://youtu.be/n1mV6m4xBF8 or @aspittel tutorial: https://youtu.be/PqtbwGUA6Fg

3. I've lost count of how many Nader youtube videos i've watched. I like this one: https://youtu.be/y4Obz26GkCk where he shows what part of the documentation is needed to piece it together. Maybe videos on each area talking through with time boxed examples of use (15mins). Probably could use an alternative way to communicate / comprehend the knowledge (maybe audio / podcast version talking through areas i.e. authentication / datastore, etc).

I hope some of these thoughts are helpful. I am still trying to build something substantial with Amplify. I'll try contributing to the solutions for the areas i've raised.

[medelman17]

Here are my thoughts generally:

"Docs" (and, for the record, I think this is a terrible term to describe the information ecosystem in which our product lives) deserve a lot more thought and effort than just whimsy--if you wouldn't launch a new feature w/o more, you shouldn't launch docs w/o same. The first step to improving our information ecosystem in which Amplify lives is to treat development of the former with the same importance and process with which you treat the latter.

To be clear, an information ecosystem refers to the users, content, and context used to address the complex dependencies that exist in information environments. Like fingerprints and snowflakes, every information ecology is unique. What brings whopping returns to one business might crush another. What works for one user might annoy another. What worked yesterday may not work today. To be successful, each project must focus its own unique objectives. We can learn from and borrow from others, but, in doing so, it is best to look at their decisions through the lens of our intended outcomes.

Any discussion related to docs must start with “Users”--our internal and external customers--and the reason they come to our information ecosystem: they have an informational need. These information needs can vary widely, and each type of information need causes people to exhibit specific information seeking behaviors. We must seek to understand those needs and behaviors, and shape our content and structure to correspond accordingly. Any dissonance between the two increases the chance that the user will give up and go somewhere else. In other words, ill-designed content and structure can negate the investment made in developing a given feature.

To use a framework, devs must learn many things: domain & design concepts behind the framework, how the concepts map to the implementation, & how to extend it. The most severe obstacles that developers face while learning new APIs tend to be related to the official documentation. Lack of code examples and the absence of “task-oriented” descriptions of the API usage have been identified as “major blockers”. Documentation that does not meet the expectations of its readers can lead to frustration, major losses of time, or even API abandonment.

Well-written docs refines the UX & resolves possible issues that could arise during product use. Good documentation makes software and tools more valuable and more durable. Moreover, good documentation reflects well on the overall competency and capability of the development team. Good documentation tends to reduce volume of support requests & erroneous bug/issue reporting. Additionally, good comprehensive documentation makes responding to remaining support requests easier. Good documentation gets knowledge out of people’s heads and into a shared format. This increases reliability, because it reduces a dependence on people’s memories and notes, which may not always be accessible, or may be inconsistent.

Moreover, without documentation users may be unaware of features and behaviors, which reduces their value. If users never learn about or take advantage of new features and functionality, then development of said resources are essentially wasted.Providing documentation that focuses on and addresses the diversity of user experiences is quite difficult. Good documentation is both technically complex and simple to read and understand. That is no easy ask.

It must thoroughly describe how a tool or product operates, how to use the product, and possible use and configuration (e.g., use cases, practical guides, case studies, etc). And so, so much more. Nevertheless, if we are to be successful, we need to see information as a workable material and learn to architect it in a way that gets us to our goals. We must exhibit the courage to push past the edges of our current reality.

Useful information cannot be designed in a vacuum. As a general matter, people only understand things in relationship to other things. Context matters. Just as the frame around a painting changes how the painting is perceived, so too does the context in which our content is presented affect our users perception thereof. Organization, management, and maintenance of information environments is a major factor in determining their success.

Unfortunately, when it comes to our use and interpretation of things, people are complex creatures. What is good for one person can be profoundly bad for another, even if their goal is roughly the same. What is needed is a systematic, comprehensive, holistic approach to structuring “content” in a way that makes it easy to find and understand—regardless of context, channel, or medium used to access it. But designing 4 needs of users is not sufficient. “Context” requires ownership of broader picture; working in the abstract, thinking systematically about challenges at hand--stepping out of the product dev trenches & looking at broader picture to understand how all fits together.

The needs of the organization and those of people who manage information are important, too. These needs must be balanced against the needs of users. Context aligns our content with the goals, strategy, and culture of our business. Owning context, requires extracting, organizing, and understanding the business context—i.e., what makes our offering unique? Where are we today, and where do we want to be tomorrow?—on an ongoing basis. Context aligns our content with the goals, strategy, and culture of our business. Like a well-designed building can accommodate many different uses over a long span of time, so, too, can a well-designed information ecosystem. When we don’t define what good means for our stakeholders and users, bad can come out of nowhere.

[medelman17]

Closing. @jakeburden -- Let's reformulate this during our upcoming one-on-ones for a more specific ask.