Added design spec for component documentation by carsongee · Pull Request #18 · datarobot-community/app-framework

carsongee · 2026-04-13T18:16:30Z

Summary

Agents and humans building and composing AF components need documentation. This specifies how to provide that in a way that they will compose properly into recipes and templates for use by humans and LLMs

Implementation for af-component-base: datarobot-community/af-component-base#81

Note

Low Risk
Low risk docs-only change that adds new guidance and a navigation link, with no runtime or API impact.

Overview
Adds a new design document (design/documentation.md) specifying conventions for where and how components should ship offline-first documentation and .skills (structure, naming, quality requirements, and sync expectations for global skills).

Updates the docs navigation (properdocs.yml) to include this new Documentation design spec under the Design section.

^{Reviewed by Cursor Bugbot for commit afe7526. Bugbot is set up for automated code reviews on this repo. Configure here.}

shreyaag-dr

lgtm

shreyaag-dr

lgtm

jendavies

Seems comprehensive, do we need more threats? :)

docs/src/design/documentation.md

jendavies · 2026-04-13T19:22:58Z

docs/src/design/documentation.md

+- Example: `docs/react.md`, `docs/llm.md`
+
+**Multi-file documentation:**
+- Format: `docs/<component-name>/README.md` (plus additional files)


Not clear what "plus" means. DO you mean:

docs/<component-name>/README.md
docs/<component-name>/deployment.md
docs/<component-name>/troubleshooting.md

If so, maybe:

Format: docs/<component-name>/<multifile-docs> (plus additional files)

Example: docs/agent/README.md, docs/agent/crewai.md, docs/agent/troubleshooting.md

I'm trying to convey that at least README.md is required in addition to any other files you want to put in the folder for a consistent experience, and to improve navigation by agents and humans

docs/src/design/documentation.md

jendavies · 2026-04-13T19:37:58Z

docs/src/design/documentation.md

+4. **Document dependencies**&mdash;External tools, environment variables, prerequisites.
+5. **Specify context costs**&mdash;Estimated token usage and context window requirements.
+
+## Implementation guidelines


Maybe link to this at the very start? But maybe you want them to read it all.

Yeah, I did. It is a bit redundant by the time you get here, but I like the TL;DR at the end these days. I'm open to putting it up top, though

I'm torn on this one, myself. I guess I'd say leave it down here for now and we'll see if it needs to be promoted.

docs/src/design/documentation.md

smagee-robot

In general, it seems good to me. I called out a few points I found confusing, but devs may understand the terms better than I do.

smagee-robot · 2026-04-13T21:32:24Z

docs/src/design/documentation.md

+
+## Overview
+
+This specification defines how documentation and agent skills should be organized, distributed, and maintained within DataRobot App Framework components. The core principle is that documentation and skills should live closest to the component they describe, enabling offline usage, ensuring consistency, and providing both human and LLM-friendly access to information.


Suggested change

This specification defines how documentation and agent skills should be organized, distributed, and maintained within DataRobot App Framework components. The core principle is that documentation and skills should live closest to the component they describe, enabling offline usage, ensuring consistency, and providing both human and LLM-friendly access to information.

This specification defines how documentation and agent skills should be organized, distributed, and maintained within DataRobot App Framework components. The core principle is that documentation and skills should live closest to the component they describe, enabling offline usage, ensuring consistency, and providing both human- and LLM-friendly access to information.

smagee-robot · 2026-04-13T21:36:14Z

docs/src/design/documentation.md

+```
+template/
+├── docs/
+│   ├── react.md                    # Single-file component docs


What is the distinction between single- and multi-file docs? Are you just referring to the difference in components that only need one doc page vs. more complicated ones? I suspect I'm misunderstanding the intent, since if it were just a single page, the README.md would likely be the choice and not react.

What is the distinction between single- and multi-file docs? Are you just referring to the difference in components that only need one doc page vs. more complicated ones?

Yep, that's the intent here

I suspect I'm misunderstanding the intent, since if it were just a single page, the README.md would likely be the choice and not react
Well, then you'd end up making a folder with one file, i.e., react/README.md, which is also reasonable. It just felt to me like it would be better for humans not to need a folder with a single file in it. I'm open to simplifying the rules, though.

With that full understanding, which way do you think is the best @smagee-robot ?

I'm fine with leaving it simple, in that case. I assume it needs to be named react for the docs toolchain as a react frontend?

smagee-robot · 2026-04-13T21:41:09Z

docs/src/design/documentation.md

+│   │   ├── README.md
+│   │   ├── deployment.md
+│   │   └── troubleshooting.md
+│   ├── llm.md


Should this be llms.md? I'm not sure of the standard (if there is one), I just recall we changed llm.txt accessible for our public docs site to be plural and want to make sure it's right, or if it matters at all.

docs/src/design/documentation.md

smagee-robot · 2026-04-13T21:46:39Z

docs/src/design/documentation.md

+
+## Implementation guidelines
+
+### For component authors


I'm not sure where it should be slotted in, but we should add a requirement that any new public-facing docs must be reviewed by the docs team.

Yeah, I feel like that needs to happen at the components creation time. Or at least when the component is ready to become an official DataRobot core component. I have a todo item for creating a guide on how to make a component from scratch. I'll make sure that I have that review from the docs team is required for inclusion in our core App Framework requirements.

That works for me. It would be nice if we get the slack integration working long-term, but in the immediate term tagging me directly should be OK.

docs/src/design/documentation.md

smagee-robot · 2026-04-13T21:54:58Z

docs/src/design/documentation.md

+
+### Naming convention
+
+**Single-file documentation:**


Nitpick: the colon for headings/callouts like this should be outside the bold tags.

(I know the actual style in this isn't the important part of the review; I think this is my only comment along these lines ;) ).

Co-authored-by: jen davies <jennifer@datarobot.com>

rabih-datarobot

This is unreal, its really nice to see the standardisation thought process put into it 🥇

damon-sava-stanley · 2026-04-14T15:16:52Z

docs/src/design/documentation.md

+
+### File organization
+
+Each component must create documentation files within the template's `docs` folder, following this convention:


With the monorepo structure, is this a top-level docs folder or say agent/docs?

Okay, seems top-level; naming subfolders should be enough. Maybe worth recommending templating docs to use same name as main folder (e.g. docs/{{ agent_app_name }}/README.md)

damon-sava-stanley · 2026-04-14T15:19:33Z

docs/src/design/documentation.md

+## Motivation
+
+### Documentation distribution
+- **Offline-first**&mdash;Components must be usable without internet connectivity.


I guess this is an extension of self-contained? Don't have essential reference to an external URL. I imagine this should also apply to skills (only uses commands prebundled in codespace?)

Added design spec for component documentation

c3131d7

carsongee force-pushed the carsongee/add_docs_spec branch from 5b525b7 to c3131d7 Compare April 13, 2026 18:28

shreyaag-dr reviewed Apr 13, 2026

View reviewed changes

shreyaag-dr approved these changes Apr 13, 2026

View reviewed changes

Update documentation.md

2efd405

carsongee mentioned this pull request Apr 13, 2026

Added docs to the base component datarobot-community/af-component-base#81

Open

jendavies approved these changes Apr 13, 2026

View reviewed changes

dr-nate-daly-pm approved these changes Apr 13, 2026

View reviewed changes

smagee-robot reviewed Apr 13, 2026

View reviewed changes

carsongee and others added 2 commits April 13, 2026 16:57

Apply suggestions from code review

4a0b24b

Co-authored-by: jen davies <jennifer@datarobot.com>

Added more details for multifile docs

afe7526

rabih-datarobot approved these changes Apr 14, 2026

View reviewed changes

damon-sava-stanley approved these changes Apr 14, 2026

View reviewed changes


		## Overview

		This specification defines how documentation and agent skills should be organized, distributed, and maintained within DataRobot App Framework components. The core principle is that documentation and skills should live closest to the component they describe, enabling offline usage, ensuring consistency, and providing both human and LLM-friendly access to information.


		### File organization

		Each component must create documentation files within the template's `docs` folder, following this convention:

Conversation

carsongee commented Apr 13, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

shreyaag-dr left a comment

Choose a reason for hiding this comment

Uh oh!

shreyaag-dr left a comment

Choose a reason for hiding this comment

Uh oh!

jendavies left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

smagee-robot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rabih-datarobot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

7 participants

carsongee commented Apr 13, 2026 •

edited by cursor bot

Loading