Improving the docs and tutorials

[Hvass-Labs]

Introduction

This is a suggestion for improving the docs and tutorials for Firebase which are located at https://firebase.google.com

Instead of just sending grumpy feedback through the web-site, which is probably just being ignored anyway, I decided to open an issue here so others can also give their opinions and suggestions, and hopefully the Firebase developers will join in the discussion, so we can find a format for the docs and tutorials that actually works for the users.

My Experience

So far I have spent several days unsuccessfully trying to get Firebase Authentication working in a simple Python Flask app. A while ago I managed to get Firestore working in an emulator, but it also took me forever to find the right docs and tutorials to get it working, and I have just hacked it together to run on my own machine, so it probably would not run securely on the actual servers.

Main Problems

First problem is that the Firebase web-site is extremely poorly organized. The nav-bar on top has the menu-item "Products" which lists "Build / Release & Monitor / Engage". Are those your products?! It doesn't sound like products - it sounds more like actions?! Then there's the "Solutions" menu-item which only has one item "Explore all solutions" - strange that it's a pull-down then. Then there's a few more menu-items including "Docs" which is probably what we need.

The "Docs" page has a gigantic amount of information probably across hundreds of web-pages that are linking back and forth to each other like spaghetti.

There is a "Samples" section all the way to the right, which only contains quick-start guides, so it should probably be named "Quick Start" and the menu-item moved all the way to the left following "Overview" so people would see that first. Unfortunately none of the quick-start guides show how to use Firebase in Python, so we have to look elsewhere.

After countless wasted hours reading through your gigantic maze of doc-pages, it seems that perhaps the "Fundamentals" menu also has some kind of tutorials - so why not call it "Tutorials"? The actual URL is called "/docs/guides" and naming the menu-item "Guides" would certainly also be better than "Fundamentals". Here there is a section called "Add Firebase - server environments" which could be right, but it has yet another gigantic maze of web-pages that are linking to each other like spaghetti.

It takes immense time and effort to try and read your docs and "tutorials"!

The overall problem is that the information is extremely poorly organized, the text is often very abstract, and constantly links back and forth to other pages for more information - almost like you're trying to write docs like you write code. And the user is required to read all this to learn how to do fairly simple tasks with your software. So you should expect that people may get a bit surly.

What I Need

I'm not a web-developer so I only have very little background knowledge on web-servers etc. I also don't want to be an expert in this field, so I don't need to know why everything in Firebase is made the way it is and how to tweak every little parameter.

I just want to build a small Python Flask app to run on Google App Engine. I don't want to spend weeks reading through your entire documentation, to learn how everything works behind-the-scenes.

I just want to know the following:

1) How do I install and setup the necessary software packages?

2) How do I make everything run on my local machine before I deploy it to your servers?

3) How do I use the various parts of Firebase: Firestore, logging, auth, etc.?

4) How do I modify my code and config-files so it runs securely on your servers.

5) How do I handle the dev / debug / deploy versions of my app in a good and secure way?

Maybe your docs have answers to these questions, but I don't want to spend weeks reading through a ton of spaghetti-docs to maybe learn the answer.

Good Tutorial Format

What I need are a few web-pages with complete tutorials and the necessary steps. At the bottom of the pages they can link to other web-pages with topics that may be relevant and have more details, but I shouldn't have to follow 10-20 links within the main text in order to try and understand the background.

Here are a few examples of such tutorials that I came across:

• FastAPI and Firebase Auth

• Flask and Firebase Auth

Neither of these tutorials are completely fantastic, but they are still much quicker to read and far more informative than the official Firebase docs and tutorials!

The problem with using 3rd party tutorials like this, is that they can easily be outdated, they may not follow best practices, and they may have big security problems that beginners won't notice. These two examples also use the pyrebase Python package, which I cannot use in my project because it is not an official Firebase release, so it may also be outdated and have security problems.

But the overall format is very useful for tutorials, because it provides complete guides for beginners that are contained within a single page. If they were written and updated by the Firebase dev-team, so all the information was correct and secure, it would be very easy for people to start using Firebase, as we could just copy-paste-edit the code and configs from your tutorials. We wouldn't have to waste days or weeks trying to read your really confusing docs.

Let's Do It!

I hope this has been a persuasive argument and that the Firebase developers will start writing such docs and tutorials. Please consider starting immediately even if it means pulling a person from another task. If we can just get the format right with a single tutorial, then you can can write more tutorials in that format in the future. If you get started immediately then I would be happy to provide detailed feedback on what is good and bad with the tutorial - but if you wait too long then I may not be available to give you feedback.

Thanks!

[google-oss-bot]

I couldn't figure out how to label this issue, so I've labeled it for a human to triage. Hang tight.

[Hvass-Labs]

@google-oss-bot If I get more tight I might snap.

[egilmorez]

Thank you very much for your thorough and thoughtful feedback. We have shared it with the Firebase documentation team (as well as engineers and other Firebasers) and will definitely give it consideration as we go forward improving Firebase documentation.

FWIW, the concerns you raise are not unknown to us. I won't make any excuses about the challenges of covering such a wide surface as Firebase, but I will let you know that we are actively working to clear more of our bandwidth for "solutions" guide content of the kind you suggest.

In fact, there are some use cases already covered by such documentation. Things like this Admob tutorial, or the groupings of codelabs we call "learning pathways" have received lots of positive feedback from developers:

https://firebase.google.com/docs/tutorials/optimize-ad-frequency

https://firebase.google.com/learn/pathways/firebase-remote-config-unity-games

Unfortunately I can't promise that, with our current level of staffing, we'll be able to cover exactly the use cases you're looking for. But I can assure you we'll keep your feedback in consideration and will continue to strive to improve our documentation to serve as much of our highly esteemed user base as possible. Thanks!

[Hvass-Labs]

Thanks! I'm glad you are so receptive to the feedback that you shared it with others.

I decided to use MongoDB because it is a much better fit for my web-app project, and I decided to implement a password-less login system myself, based on an idea I saw in one of your Firebase tutorial videos. So I won't be needing Firebase / Firestore after all.

But allow me to make another suggestion, because it is a common problem with Google's documentation and tutorials, that it can be quite difficult to understand, especially for beginners in that particular field.

So when you make your new documentation and tutorials, you may consider "testing" it on beginners who are not familiar with your products, and who are representative of the skill-level that you expect of your new users. Then observe what they find difficult to understand, so you know which areas you could improve.

Some years ago I made a series of TensorFlow tutorials that were quite popular, because they were thorough yet still fairly easy to understand. The reason was that I too was a beginner when I made them, so I had in fresh memory what was hard to understand about TensorFlow, so I could explain those aspects to others.

When experts are writing documentation, the problem is that they are often far removed from the beginner-stage, so they naturally become unaware of what is difficult for beginners. So "testing" the docs and tutorials on beginners would probably help.

Writing good documentation and tutorials is not trivial, and it is often an under-appreciated skill.

Feel free to close this topic when you have read this.

[jonathanedey]

Closing this as requested.