[RFC] Documentation Website Feedback

[Ehesp]

Hey all

We're looking at giving the documentation a refresh and would love some feedback from users who regularly use the library/docs.

Currently we have 2 websites, one for v5 & one for v6+. Right now, the docs are a bit all over the show and we'd like to rework how they are presented for v6+. The v5 website will be kept as-is for now.

In hindsight, we made an error with the docs by putting most of the examples of actual code usage within the Reference API docs. This makes things really hard to find given the volume of pages/API surface area.

The general feedback from the website "Send Feedback" form is:

• Not enough information / examples.
• Too much clicking about.
• Finding practical examples of usage.
• Confusing installation instructions (e.g. app being required on each module).
• Navigating around is tricky.

Whilst developing the docs, the main problems we have are:

• Firebase vs own examples. Do we need to effectively copy-paste examples from the Firebase docs on usage? Personally I feel this is redundant given some APIs are exactly the same.
• Should the Reference API docs be alongside the main content?
• Should examples be in JavaScript/TypeScript/both?

We also tried to be too fancy, adding in blocks/icons rather than just sticking with good ol' HTML.

The general idea is to go down the same route as the Notifee docs, and keep the reference totally separate from the actual written documentation.

If anyone has any feedback/ideas please let me know so I can start planning the update!

[BadMask121]

To be honest, the website documentation doesn't help much, it's confusing, after the get started page everything else is out of place, hopeful this gets fixed.

[Lucas-Geitner]

hello, I think it's just a bug on safary, but on mobile, we cannot close the menu, which mean the website is not readable,

Thanks

[Salakar]

To be honest, the website documentation doesn't help much, it's confusing, after the get started page everything else is out of place, hopeful this gets fixed.

Honesty is welcome @BadMask121, thanks for the feedback - if you have anymore then keep it coming 🙃

[somoso]

Hello, rootfs.ext2.gz here! Confirmation tweet here.

First of all, I want to apologise for the harshness of the tweet. Looking back, I (believed I) was shouting into the Twitter void to vent without any expectation that anyone would read it. Now that's it's here, I feel a bit embarrased.

I also want to say I 100% appreciate the effort the Invertase team has put into react-native-firebase. What my grouchy tweet failed to mention was that I've been following this project for quite some time, and it's only recently I got the chance to migrate one of my projects from an old, outdated, and unsupported react native firebase library to react-native-firebase, but I've been following this project for some time, and I've always been impressed with the quality.

With that said, my tweets were real frustration, and you've done a great job of recognising some of my complaints. My overall issues are:

• I have to have multiple tabs open just to read what I believe should be an A-B-C configuration. For example, I'll click on "Integrate into Existing Project" and then I get a brief snippet of code and instructions before being given a fork in the road over whether I want to integrate either iOS or Android, and this goes into a new page. Since I support both (and why wouldn't I? If I wanted to support one platform, I'd code natively and skip React Native altogether) I have to open both pages whilst keeping the current page open because I'm trying to mentally model how I'm going to integrate this project. And this is just for the Firebase Core.
• When it comes to the actual submodules, the code integration is absolutely fantastic, but trying to figure out how to use them is frustrating. Partially for the above reason, partially because I cannot get any decent "Quick Start" guides and just trying to get to the API listing is confusing. I just want to know a trivial least-amount-of-code example on how to get Firebase Cloud Messaging working!!
• I made a final point about this, but having a link to your Github page is a lifesaver. Sometimes I google projects and wind up at the project's fork. Sometimes I have to wade through Google's Firebase documentation - which while nice, I want to see your project. Maybe I want to peek at the code just so I understand what it's doing underneath the hood. Maybe I want to see the issues page just to understand if a bug I'm seeing really is me or if I've hit something (this actually happened this morning, and it wasn't just me). Please link to the Github project on your docs.
• As I was writing up my example documentation, I couldn't help notice there was guides on how to create a Firebase project. While it's nice for newcomers to have that, I think it's a bit outside the scope of this project and really should be left to Google to explain to its users how to create a Firebase project.

With that said, I wanted to put my money where my mouth is and produce an example of the type of documentation I'd like to see - expose myself to some criticism for a change. I've taken some of the documentation from the React Native Firebase page and placed it here in essentially one page. But that page was at least 5 separate pages of React Native Firebase documentation pages all laid out on one page I can scroll back and forth for more info.

I also cut out a lot of the wording and got straight to the heart of the matter and just gave the code examples - I know it's something as an end user of react-native-firebase I want to see over lots of words. I wanted to add more examples - including a Cloud Messaging quick guide example, but I'm in a bit of a rush as I'm running out of time. If I have some more spare time in the future, I'll see about how to exand it.

Feel free to critique this answer or ask for more clarification. Most importantly, thanks for taking on feedback!

[Salakar]

@somoso thank you for the feedback, constructive feedback is always welcome and I understand where your frustrations have come from when using the docs, we're working on it and your feedback is super helpful, so thanks!

[Ehesp]

Hey, so I've been tinkering with an updated docs website based on feedback. Generally going for the "least clicks, more content visible" approach and cutting out the fluffy UI bits (e.g. keeping to plain lists). Also, I've removed the reference from the main part of the website, and it'll be in its own section to avoid any confusion.

Here's what it looks like, although very much WIP!

[somoso]

That looks very promising!

[Ehesp]

Another update... we're working through the docs (guides etc), still a fair bit to do but coming on well. Reference API wise, this is now totally separate from the guides so it wont be as confusing:

[somoso]

It looks very nice, but I'm a bit unsure about what is presented. From my perspective as a developer using your APIs, how does knowing the interface exists help me with my code?

I think the best example of a reference API is React Native. They specify each component as a new page (which I think is fair - having to scroll all the way down for some cloud messaging APIs is a bit ludicrous) and on each page they show all the props that a developer can use on a component and all the methods that are publicly available.

Seeing as your code essentially acts as a shim layer to the real Firebase APIs on the native platform, but implemented in the style of the Web framework, it might be useful to have a list of usable endpoints that point to the actual firebase doc, only adding extra info like in the React Native documentation for API endpoints that have been modified for whatever reason.

Example:

• deleteToken
• getToken
• onMessage - implemented as onMessage(notification: Notification): fn(). Passes a callback to unregister the onMessage handler - use this on componentWillUnmount in your React class or utilise useEffect.
• etc

For the onMessage, since the implementation differs slightly, I'd expect to see an example. For deleteToken/getToken such examples is not necessary.

[Ehesp]

@somoso The existing website has the following-ish site structure:

/docs
  /getting-started
  /... other generic pages

  /:module
    /overview
    /quick-start
    /reference
      /:type-api

Although this does work, the feedback we've got indicates users are getting lost trying to find workable examples within the reference, because they dont really know what they're looking for in the first place.

The new site will totally move reference out into it's own section, and put readable content first, e.g:

/getting-started
/... other generic pages

/:module (e.g. admob)
  /:setup
  /display-adverts
  /european-user-consent
  /... other admob guides

/reference/:module
  /:type-api

Users will only view the reference if they want to look at details & sepcifics. The actual pages for each module will be written by us to act more as a guide for users, and how it can integrate with your own code.

[Ehesp]

If anyone is interested: https://rnfb-docs.netlify.com/

Heavily WIP, working through adding content / moving stuff over at the moment.

[andersonaddo]

My two cents (just minor things):
Will the sidebar the left be collapsible?
Is it possible to make the table of contents on the right highlight the section you're at?
The margin on the left of the sidebar seems needlessly large.

[Ehesp]

Thanks!

Will the sidebar the left be collapsible?

Do you mean the menu items? If so, I was thinking of doing that but just felt it made finding the content you're after much easier.

Is it possible to make the table of contents on the right highlight the section you're at?

Nice idea, will look into it.

The margin on the left of the sidebar seems needlessly large.

That's just the space left from having the content centered. Do you have any other suggestions as to what to do with it?

[andersonaddo]

Do you mean the menu items? If so, I was thinking of doing that but just felt it made finding the content you're after much easier.

No, I'm talking about the sidebar itself. The pages are longer now, which means people will spend more time reading and less time navigating. If that's the case, then the sidebar shouldn't be taking real estate all the time - users should be able to collapse the sidebar like a drawer.

That's just the space left from having the content centered. Do you have any other suggestions as to what to do with it?

Content in the sidebar shouldn't be center aligned because it kinda wastes space that could and should be used for the main content. Ofc, its less of a problem if the sidebar is collapsible anyways, but the content should be left aligned with margins and padding providing the appropriate spacing.

Upon better retrospection:
I think that's an indication of the sidebar getting too large with larger/wider screens. The responsive sizing of the side could be better to prevent it from growing needlessly large.

[andersonaddo]

Also, I'm curious about the edit buttons? (thought about this and also #3115)

[Salakar]

New site is live; https://rnfirebase.io/

Feedback extremely welcome.

[sevencrises]

does anybody has a link for v5.x.x docs I can't access it. sorry if this is not related but I've searched all over the place and can't seems to find it :(

[mikehardy]

They used to be https://rnfirebase.io/docs/v5.x.x/getting-started
@Salakar there are still about 50/50 users on v5 vs v6 via npmjs.org download stats I think. v6 now has primacy but there's lots of users that still need those v5 docs as everyone works through RN59->RN60 and the notifications switch here. Going to be a long process

[Ehesp]

V5 is still available on https://v5.rnfirebase.io - will update the readme

[Salakar]

Unfortunately rnfirebase.io still comes up everywhere as the first site you go to when you want to integrate firebase into RN - so we had several people report that they started integrating v5 instead of v6 (despite the big red banner at the top 🙈) - so this is the main reason of the switch

Docs for v5 haven't gone though, just made v6+ now the default as v5 is no longer in support. We'll make finding the v5 docs a bit more obvious.

The 'old' v6 docs domain and urls should all 'work' and redirect to the relevant place on the new docs, we setup a custom redirector so that nothing or most things shouldn't be broken

[mikehardy]

I get it :-), is there a way to make the '/docs/v5.x.x' redirect to v5.rnfirebase.io for all the links out there? And you can always make the banner a popup and full screen hahaha. Silly but maybe needed. And just for the avoidance of doubt though I'm still currently on v5 and support it I am 100% for v6 and seems like notifee iOS about to drop it's time to move myself. I'm just looking out for all the folks stuck on creaky codebases with no time to really refactor, already starting at so many upgrades...

[Salakar]

I get it :-), is there a way to make the '/docs/v5.x.x' redirect to v5.rnfirebase.io for all the links out there?

Already on it, we'll sort

[Salakar]

Cool, sorted, old <= v5.x.x links will work now, e.g. https://rnfirebase.io/docs/v5.x.x/getting-started

[mikehardy]

<Accent mode="New_Zealand">Legend</Accent>

[dhuber666]

Add a line to the installation guide that multidex has to be enabled. Because every time I set up firebaes in an existing project I get the error that there are too many multiDex sessions. What ever that means.
The solution is to just simply put a line into android/app/build.gradle

defaultConfig {
        applicationId "com.reactnativenavigationreduxstarter"
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        versionCode 1
        versionName "1.0"
        multiDexEnabled true // add this
    }

Please add this in the docs.

[Ehesp]

Is that any module? I've only ever gotten the error when I add it on firestore. There is a point in the usage docs about it, but not for the entire module.

[dhuber666]

@Ehesp it's the getting started guide. Where you set up the whole project. I tried it 3 times and always got some errors with that multiDex thing.

[Ehesp]

cc @mikehardy I'm not too familiar with how Dex impacts apps, but I've only ever had it when installing Firestore due to the size of the lib. Do you think it'd be better placed at root?

[somoso]

@dhuber666 In Android 5.0 and higher, multidexing is enabled right out of the box as standard as part of ART (Android Runtime, replacement for Dalvik engine). You can read more about it here.

As of speaking, I'm looking at the Distribution Dashboard and all devices running Android 5.0 or higher count for 89.4% of Android devices out there. While I'm unsure of your business requirements, wouldn't it be safer and easier if you adjusted your rootProject.ext.minSdkVersion to 21 so you can take advantage of easier compilation?

[mikehardy]

@somoso I dislike this advice for two reasons 1) you make assumptions that the general state of android API distribution is the specific distribution for any developer (I target my apps at developing countries for instance and the API skew is older) and 2) why would you arbitrarily choose a cutoff when the technical solution is easy and well-supported? So I would never advocate raising minSdkVersion above that supported by the general ecosystem (that'd be react-native which works down to 16)

@Ehesp it's possible that any given combination of non-react-native-firebase modules might cause the need, and it's known that within react-native-firebase itself the need will be triggered (firestore), plus I don't see any performance or other reason not to implement - I always do personally, so I'd just advise people to do it straight away personally, perhaps with a note (and a nod to @somoso ) that if your target is 21+ then you don't need to but otherwise it's the safest route

[dhuber666]

@somoso @mikehardy @Ehesp

Sorry I'm just a first time user and can't help in any of this. I can just say as a first time user, I follwed the docs and I had this multiDex Problem. So I tried it again with a new project and same problem. So I thought I write this here, in case this has to be updated, so new users know what to do when they get this error.

[Ehesp]

I've added it to the root of the docs (88b58eb).

[dhuber666]

@Ehesp Awesome thank you :)