Add resource links to user guide intro page

[ghislaineguerin]

The current intro page is quite limited and doesn't guide users to additional resources. I propose that we add links to other pages to improve navigation until more content is added.

Developer Certificate of Origin

Developer Certificate of Origin

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

[seancolsen]

I'm sorry, but this is one of my biggest pet peeves with documentation. And since this topic has come up before, I want to explain my thinking on the subject in detail.

I really don't like it when navigation is duplicated within page content. Generally I go to great lengths to avoid doing this. I'm fine with specific cross-references when they are contextually relevant. Even sections like "Related Pages" are fine with me, so long as they are curated intentionally and do not serve to duplicate top-level navigation. What I don't like is content that simply lists child pages that already occur within the navigation menu.

While this pattern may indeed help a reader on one particular page, my point is that it ultimately detracts from the docs navigability by introducing inconsistent navigation patterns. In site navigation, consistency is paramount! Any inconsistencies have the potential introduce subtle subconscious barriers for readers to learn the sites navigation and structure. Providing a navigation menu within the content of a page teaches readers to look for site navigation within page content. That sort of navigation might be fine if all pages have it. I've seen wikis that work this way. I have no problem with it, so long as that navigation is auto-generated and not manually maintained in duplicate. But if some pages have site navigation in content and other pages don't, then the site can become confusing to readers. To be clear: in my experience, most readers do not consciously identify this sort of confusion. It's not the sort of thing people complain about. Instead, they just end up struggling a bit more when navigating a site, and they end up with a vague feeling of "things being hard to find".

In addition to degrading site navigability, this pattern also degrades site maintainability. At the very least, storing navigation lists in duplicate requires more work because changes must be made twice. But even worse is the high likelihood that editors will fail to recognize that changes even should be made in two places, leading to further navigation inconsistencies.

Our docs already have this problem, and provide an excellent example of why I don't like this pattern. On the home page we have links to some (but not all) user docs pages:

Looking through the history, we can see why:

1. In More updates to the docs #2612 @kgodey added this content to the home page.
2. Then, four months later, in Added documentation for importing data into tables #2992 Anshuman added a new page documenting the import process. He added the page to the site navigation menu, but (understandably) didn't think to look for other ad-hoc navigation lists that might require that new page as well.

What to do then?

We have this Using Mathesar page which looks very sparse. I agree that it could be improved! But I don't think that simply adding links within that page offers any meaningful improvement. It might make that specific page look a little better. But it comes at the consequence of degrading navigability of the docs as a whole.

Instead, it would be better to flesh that page out with more content. What are some of the basic things I need to understand when starting to use Mathesar? At a high-level, how do users's interact with Mathesar? Within our docs, what's the different between a "user" and an "administrator"? What is a "database"? What is a "schema"? What is the internal database, and how is it different from the user database? What data is stored in the internal database vs the user database? These are all questions that I might consider answering on that initial "Using Mathesar" page. Such content could potentially link out to other pages which expound on those concepts, but those links would be embedded within paragraphs, as cross-references, not navigation.

Producing all that content requires work. Until we decide to do that work, I'd argue for leaving this page alone.

[ghislaineguerin]

@seancolsen I see your point. I agree that the issue is probably the content itself. I will close this and we can maybe revisit this page later. I just think it might be confusing to link to this page as a resource as it is so sparse as you mentioned.

[kgodey]

Instead, it would be better to flesh that page out with more content. What are some of the basic things I need to understand when starting to use Mathesar? At a high-level, how do users's interact with Mathesar? Within our docs, what's the different between a "user" and an "administrator"? What is a "database"? What is a "schema"? What is the internal database, and how is it different from the user database? What data is stored in the internal database vs the user database? These are all questions that I might consider answering on that initial "Using Mathesar" page. Such content could potentially link out to other pages which expound on those concepts, but those links would be embedded within paragraphs, as cross-references, not navigation.

I agree with this direction. @ghislaineguerin If you wanted to actually write this documentation, I think that would be a fine thing to work on.

[ghislaineguerin]

@kgodey Yes, I'd like to work on that.