Restructure and extend documentation

[msiemens]

This is a note to myself to rework, restructure and extend the documentation based on the principles layed out in https://documentation.divio.com/introduction/ (and https://v3.vuejs.org/guide/contributing/writing-guide.html for that matter).

I considering adding a how-to section in the process. If anyone has ideas about what topics would be useful for short how-to guides/articles, feel free to comment on this issue 🙃

[eugene-eeo]

probably writing extensions, with a little description of the internals (how to extend the code?).

[vincentdavis]

It's been awhile since I worked with TinyDB and I was looking up how to use db.upsert.

>>> db.upsert({'name': 'John', 'logged-in': True}, User.name == 'John')

This is confusing because User.name is defined near the top of the page, I was thinking to myself, is User a table or another database? There are several places with this type of issue. It makes the otherwise awesome documentation a little difficult to use as a reference because the examples are not complete.

I would be happy to help with documentation or short how to guides or examples.
I am currently working to import data from Excel files doing a lot of db.upsert and field transformations. I could do some examples like this.

Point me in a direction and I can help some.
Thanks for TinyDB!

[msiemens]

This is confusing because User.name is defined near the top of the page, I was thinking to myself, is User a table or another database?

That's a good point. Basically the current documentation assumes that it is read from top to bottom. Instead we should split it into more subpages that have self-contained examples.

I would be happy to help with documentation or short how to guides or examples.

That's great! 🙂 I think we should have an examples section that contains commonly used operations. If you like you could contribute your experience from working with TinyDB about what examples would be most helpful. I'm still not sure how to organize this best. Maybe I'll start a pull request where we could have discussions about these matters. Or maybe start collecting examples in the GitHub project wiki. What do you think?

[msiemens]

Note to self: document using upsert with Documents

[mateustoin]

Hi @msiemens, how are you?

I really like this project and the repository. I ended up coming across this issue about open documentation. Regarding the references you provided when you opened it, I've been thinking about contributing.

I believe that tinydb is very good and relatively well-known, but perhaps what could attract more people and uses would be some tutorials and how-tos teaching and showing specific and simple applications. I thought about suggesting one or two tutorials and how-tos for the documentation and at the same time trying to include them in blog posts, especially in other languages ​​like Brazilian Portuguese. What do you think? I already have some examples of simple use in simple applications.