New engineering wiki structure

[kgodey]

I'd like to refactor the structure of the Engineering wiki section to make it more useful.

New proposed structure

Top level bullet points are top level sections, second level bullet points are nested sections, etc. [NEW] indicates new pages I'd like to create.

• [NEW] Getting started
  • [NEW] Codebase overview
    • [NEW] Backend code overview
    • [NEW] Frontend code overview
  • [NEW] Local development environment setup
  • Common issues
• Coding standards
  • API standards
  • Front end standards
  • [NEW] Back end standards
• Code review process
  • Backend code review guidelines
  • [NEW] Frontend code review guidelines
• [NEW] Glossary
  • UI Types
  • Filters
• Technical design documents
  • Number display and entry
  • Human readable dates and times
  • Import previewing
  • Syncing database objects
  • DDL operations
  • DML operations
• Resources
• Archive
  • Engineering decisions

Notes

1. I think this is more in line with how we're using the wiki. It gives us a clear place to put different kinds of documents and will also help contributors get up to speed faster.
2. We're not keeping the "engineering decisions" page up to date, so I think it makes sense to archive it.
3. For pages that are getting moved around in the hierarchy, I'll keep the existing page up but replace the contents with a "This page has been moved" notice.

Feedback

• Please leave thoughts/suggestions/concerns etc. in the discussion comments.
  • It would be useful to leave a comment even if it's just "Looks good".
• Prompts for thought:
  • Does the new proposed structure make it clearer where future documents should go?
  • Is the purpose of each section clear?
  • Are there any types of documents that I'm missing?

[seancolsen]

Love it!

[pavish]

Looks great to me!

Can we have dedicated setup pages under Local development environment setup?

• Local development environment setup
  • Setup for Linux
  • Setup for Mac
  • Setup for Windows

[kgodey]

Yeah, that should be fine.

[kgodey]

I've implemented the new structure, although most new pages need more content. I'm tracking that work in mathesar-foundation/mathesar-wiki#41.

For pages that are getting moved around in the hierarchy, I'll keep the existing page up but replace the contents with a "This page has been moved" notice.

I didn't do this for all pages, because it's a lot of old pages to maintain and also when you're navigating the wiki via folder structure, all the extra pages get confusing. I only retained the "Common Issues", "API Standards", "Front End Standards", and "Architecture" pages because those are likely linked from a bunch of places.

[silentninja]

We're not keeping the "engineering decisions" page up to date, so I think it makes sense to archive it.

I do agree that we are not maintaining it but there isn't a better place to list the conventions we use for our codebase. For example, to specify that column attnum should be used for DML operations instead of the column name. Writing a spec for larger issues such as Date format make sense but engineering decisions is handy for smaller conventions. I would also like it if we could document the summary of a spec and point to the spec document for details so that "engineering decisions" would be a good starting place for new contributors.

[kgodey]

@silentninja I think it's better to document code conventions in the Standards section, that's where we have API standards defined. We could start a db module standards page and add to it as needed.

I think the fact that we haven't updated "engineering decisions" since June 2021 is a good indication that it's a process that's hard to remember. If we don't include all decisions on it, it becomes misleading to use it as documentation.

We have been adding new specs, standards, and glossary items fairly regularly, so I think it makes sense to standardize on those sections.