[Request] Complex Coda Docs — Mapping them out for sustainability and continuous development

Marketplace Requests and Gigs
2

Hey Sonny,

Not sure if this is what you’re after, but here are some quick tips. These are the best practices I discovered while making my own docs and building docs for hire. Right now it’s just a list — I’ll expand more on it in my upcoming blog codatricks.com

The most important piece of advice is:
Always assume two roles: doc builder and doc user.

Which means, always have a view into your data that’s convenient for a doc builder (where nothing is grouped or hidden, and all the data structure is apparent), and always provide good UI/UX for end users (e.g., well-formatted views, prominently visible controls, links etc).

Here’s a set of tips:

  • Keep all your master tables separate from user-facing content. Ideally place each master table in a separate section, all sections in a dedicated folder named “Database (do not touch)” or such. Only use views throughout the rest of the doc. This is the most frequent sin I see throughout people’s docs.
  • Keep master tables ungrouped, unsorted, unformatted, with all columns visible. It’s much easier for a doc builder to work with this than with any other display setting.
  • When changing table structure (e.g. adding columns, editing formulas), always do so in the master tables. Then make new columns visible in views. Not the other way around.
  • Establish some naming convention to tell apart master tables and helping tables from views. E.g. prefix master table names with DB and helper tables with _.
  • Always prefer verbose table and column names over cryptic short names. It’s better to name a column with 6–8 words (e.g. “Number of non-failed contracts starting this month”) than name it e.g. “Contracts” and stumble on it each time later down the road.
  • Break down formulas into smaller pieces. Split down a column formula into several steps (several columns) if you feel it becomes hard to follow, even if you’re not going to reuse any intermediate calculations. As a software engineer, use your best judgement as you would when splitting one long expression into multiple temporary variables.
  • Use chaining instead of wrapping (e.g. Table.Filter(...).First(), not First(Filter(Table, ...))). Almost all Coda functions support this syntax. It makes formulas much easier to understand for everyone on your team and for you later because it reads like a chain of steps.
    More
  • Put effort into formatting your formulas with line breaks (shift+enter) and indents (2 spaces works best). This takes time, but makes formulas much more maintainable.
    More
  • Use correct column types. When using lookup columns, pay extra attention that a) you select a right table, and b) you properly select whether multiple items selection is turned on. When writing lookup formulas, be explicit if you want to only select a single value by using .First() in the end — otherwise the type would be inferred as “a list of one element” and you’ll run into issues when using that result in further calculations.
    More
  • Avoid using .ToText(). Usually it’s misused to convert a row reference into a string, e.g. to remove links / “blue text” or when it’s needed to compare a lookup column to some string. This will break if you change your display column. If you find yourself typing ToText(), stop and think again. Maybe what you really want is dereference a specific column instead.
  • Discourage any possibility for users to mess up table display settings. Instead of making end users change filters, grouping, sorting etc via dialogs (the hidden icons in table headers), provide obvious in-canvas controls like here.

This is what comes from the top of my head. I probably forgot something. And yeah, this is basically an outline for my upcoming article on best Coda practices on my upcoming blog. It’s just much harder to write a proper article than type out this reply in a single take :slight_smile:

34 Likes