You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Currently all the documentation is on one long page. This was fine initially but now the amount of things we are documenting has outgrown our one pager.
We should split the documentation into multiple pages. This is better for SEO and makes it easier for people to link to different pages. Also currently we are using smaller and smaller headers for each sub-section, which is good because it shows visual hierarchy, but we are nesting so deep that the font sizes are getting super close to the normal text size.
Inspiration
I really like the Apollo docs, they have the same issues we have with regards to catering to different types of users, in their case their split is Client, Engine and Server. I think it would be good to borrow some inspiration from them with regards to our own docs.
Redux is another project that has lots of (nested) documentation, they added another navigation on the right side of the page. That could also be an option for us if we'd want to clean up the navigation a bit.
The text was updated successfully, but these errors were encountered:
The downside with waiting with this is that when we do decided to split the docs into different pages, redirecting people is going to have to happen on the client side and which will mean that it won't get picked up by search engines that easily. The longer we wait the more comprehensive our redirects will have to get on the client side, because more people will start linking to our pages with the page anchors.
Now the site is still fresh and young and the inbound (deep)links are still somewhat limited we have the chance to not get ourselves into too much technical (redirect) debt.
Currently all the documentation is on one long page. This was fine initially but now the amount of things we are documenting has outgrown our one pager.
We should split the documentation into multiple pages. This is better for SEO and makes it easier for people to link to different pages. Also currently we are using smaller and smaller headers for each sub-section, which is good because it shows visual hierarchy, but we are nesting so deep that the font sizes are getting super close to the normal text size.
Inspiration
I really like the Apollo docs, they have the same issues we have with regards to catering to different types of users, in their case their split is Client, Engine and Server. I think it would be good to borrow some inspiration from them with regards to our own docs.
Redux is another project that has lots of (nested) documentation, they added another navigation on the right side of the page. That could also be an option for us if we'd want to clean up the navigation a bit.
The text was updated successfully, but these errors were encountered: