Documentation improvements discussion

merfire commented 4 years ago

Issue type:

[ ] bug report [ ] feature request [x] documentation issue

TypeORM version:

[x] latest [ ] @next [ ] 0.x.x (or put your version here)

I am opening this issue to start a discussion about improving TypeORM documentation. I have created a repo using VuePress to make TypeORM documentation better and to demonstrate the benefits of this approach. I picked VuePress because it looks the most similar to the current design and is well supported.

Current problems:

Docs are not SEO-friendly, for example when you Google search for TypeORM docs you only get typeorm.io landing page (no other pages are indexed) and docs on github that are hard to search. In VuePress each Markdown file is compiled into HTML that can be easily crawled and indexed by search engines.
Docs are not searchable. Currently in VuePress example repo I am using vuepress-plugin-fulltext-search package that provides fulltext search using flexsearch library. Even though I have come across some problems using this approach, it is a lot better than no search. Recently I have found that Algolia provides free search for documentation and powers a lot of popular open source projects. For search, I think Algolia would be the best approach.

I would like to ask @pleerock and @imnotjames is such a change desirable and what everyone else thinks about this?

imnotjames commented 4 years ago

This would work great if we were maintaining the documentation in a separate repository - except we aren't doing that. Does this handle that case?

merfire commented 4 years ago

I don't see why this wouldn't work in both cases (setting it in the current repo like it is now or in a new one). Now a question is what would be better? I think this comes down to personal preference, I see a lot of popular open source projects do it either way.

DNature commented 3 years ago

I don't see why this wouldn't work in both cases (setting it in the current repo like it is now or in a new one)....

Setting up a separate repo for documentation would be much better and easier to maintain and track issues.

I created the documentation of nature-ui using Nextjs, Markdown, and Algolia, and we can easily customise the codebase for this use case, so we have fewer things to worry about since the documentation is written in Markdown.

It's accessible, SEO friendly and follows best practices.

@merfire @imnotjames @pleerock

benediktms commented 2 years ago

I agree that it would be great if the docs were at least searchable. There solutions like Docusaurus 2 that seem (at a quick glance) like a good way to tackle this. Are you open to considering moving the docs to a standalone repo? I appreciate that setting all this up would require time and effort. I'm willing to help if I can.

dheysonalves commented 2 years ago

I agree with @DNature , moving to a standalone repo would be nice to maintain. Even so, there are repo out there that works as a standalone or docs. I'm willing to help as well to move this foward.

merfire commented 2 years ago

I think Docsaurus 2 would be a great solution, it covers all the points I mentioned and also has built-in support for Algolia search, I think typeorm can easily apply and get free for open source projects Algolia package.

DNature commented 2 years ago

The quickest way I could think of, to get things up and running is to fork "Nature UIs " documentation website as it also includes Docsaurus 2 and Algolia.

Just a few theme tweaks and everything will be set, before migrating the docs.

I'm open to help with the setup, and also further discussion.

DNature commented 2 years ago

I think Docsaurus 2 would be a great solution, it covers all the points I mentioned and also has built-in support for Algolia search, I think typeorm can easily apply and get free for open source projects Algolia package.

Yeah. The application process is pretty quick.

wanton7 commented 2 years ago

Our company is converting our server app from Objection.js to TypeORM. I have to say documentation not supporting search has been a horrible experience for us and have really slowed us down. I mean if you don't support search then please just have the documentation in one page like they do in http://knexjs.org Also many things seem out of place. I was for example looking how to load relations with find. There didn't seems to any documentation for that at https://typeorm.io/#/relations or in https://typeorm.io/#/repository-api. But found that under https://typeorm.io/#/many-to-many-relations Many similar cases where that it's just VERY hard to find anything from the documentation. Just now trying to find out how to start supporting soft delete, wish me luck that I don't spend lot time just looking for the docs. I bet soft delete documentations will be spread all over the place as well.

DNature commented 2 years ago

@wanton7 , Indeed it's adds a considerable layer of difficulty. I was rebuilding a new documentation website for typeorm but had to pause because I moved to the Netherlands and trying to settle down. It's hard to work on open-source & a full time job at the same time

wanton7 commented 2 years ago

@DNature I can understand that it's not always easy to support open source projects. Great project but we are having bit of growing pains because we can't find things. Eventually this of course goes away later in the project and maybe future projects when we know how things are done. When we examples in our own code base.

typeorm / typeorm

Documentation improvements discussion #6964