Makers, how do you document your docs?

[Sebastien]

I remember from my long-gone days as a developer that great code documentation is vital for long-term projects. Cue a couple of head-scratching moments when re-opening earlier Coda docs… So I started writing comments in the doc itself, e.g.

=if([toggle implementation notes],"A helpful comment on what's going on"," ")

with a toggle in a Setting page to turn them on/off. They stay (almost) invisible for normal users.

But I’m sure others came with better ways! Do you have any best practice for doc design documentation?

Thanks,
Sébastien

PS: I saw recently an interesting suggestion

@Paul_Danyliuk

Comments in formulas — e.g. /* like this */

[Marko_Petrovic]

I used a hidden page inside document to “explain” all the relations, formulas, workflows etc, but there are for sure more efficient ways to do it
Also formula comments would be such a nice addition, with the complexity you can achieve in Coda I start to think they are must

[Fran_Vidicek]

Comments in formula editor +1
Vote here if you haven’t already: // Comments in formulas

[Agile_Dynamics]

i once had a client who wanted me to provide descriptions for every column in every table in the doc we built them.

so i created a page for each table with a detail-view for that table.

in the edit-layout for that view, i provided a description in the extended-label field for each column.

that way the documentation was attached directly to the table and columns, but otherwise was hidden from the users.

it worked and seemed like a clever way to document stuff. but it was a pain in the arse to do, so i never did it again.

max

[anon42122166]

That is clever! My dream for table documentation is a text box built right into the column options dropdown. Currently, I do a “Source Tables” section with a table per page, and include a description and a bulleted list right in the canvas about the table, but it’s a pain and there’s no way for it to be in context of any views.

[Blaise_d_Estais]

3 tricks:

a dropdown [>>] with a “” / “info” / “readme”, to say people should read here for documentation/explanations. It would be nice if it could be default open or some kind of callout, especially for first time coda users, who see the doc as an app, and who don’t even know the concept of a dropdown that they can expand/collapse

a gslides, w/ screenshots and explainers, embedded in the first page of the doc

a page where I take team mates through a process step by step, explaning them each and every table cell they need to fill, with like 10 views that have 1 column and 1 line each, so I guide them very very very closely. but a “little” long setup ^^