Strategy for codelabs/living documentation

[matanlurey]

Maybe this is "solved" but I'd like to see us create a series of small codelabs that are "living", that is, are updated as the packages are updated, and are required to pass (on travis, or at least on travis-cron if they take longer than we'd like).

Some ideas for a /codelabs folder:

• Using build_runner to serve a web application
• Using build_runner with AngularDart
• Using build_runner with Flutter (maybe built_value as an example?)
• Creating your first builder
• Creating an aggregate builder (#926)
• Working with resolved Dart source code
• Debugging builders (with observatory, breakpoints, logging, etc)
• Customizing the build process

/cc @jakemac53 @natebosch @alorenzen

... and ...

/cc @kevmoo @kwalrath @chalin who might have ideas on how to do this properly.

[jakemac53]

love it, we have e2e_example which has become more of just our integration test suite, but I think expanding that out into angular examples etc would be both good for documentation and making sure we don't break things

[kevmoo]

We could have a /codelab/001_intro /codelab/002_xyz each as their own package in the mono repo....or something.

[kevmoo]

The question: would this be better as part of https://github.com/dart-lang/site-www/ somewhere.

A good discussion to have w/ @kwalrath

[jakemac53]

The main advantage of keeping it in the mono repo is we can easily run the tests on each submit, but we could rely on cron jobs instead that are pointing at our master branch and building once a day or something.

[chalin]

Great idea to expand the docs and examples we have to include build related use cases.

I agree with @kevmoo: let's ensure that we publish such docs and examples through the proper channel. E.g.,

• Using build_runner to serve a web application
• Using build_runner with AngularDart

will (soon) be covered under webdev (https://github.com/dart-lang/site-webdev). And we have living examples and docs with travis run tests and checks. In particular, we run both component tests and E2E tests (using the new build system), as shown in this Travis log.

[matanlurey]

@kevmoo:

We could have a /codelab/001_intro /codelab/002_xyz each as their own package in the mono repo....or something.

Yeah, that's my thought right now.

The question: would this be better as part of https://github.com/dart-lang/site-www/ somewhere.

It would be more visible, but to be honest I'm not a huge fan of the current setup of the documentation for packages and processes living independent of the code:

• It relegates tech writers to the position of "figuring out what changed", they shouldn't need to
• It makes engineers stop thinking docs are important, because we don't see/update them
• It constantly breaks the workflows that are documented, because we don't see/run them

I could see value in site-www mirroring docs/code that live in this repository, but to be honest I'm just not happy with how the language and AngularDart docs are managed, and I want us to try and do better here.

@jakemac53:

The main advantage of keeping it in the mono repo is we can easily run the tests on each submit, but we could rely on cron jobs instead that are pointing at our master branch and building once a day or something.

Right. I think the main advantage of the mono_repo is we update the docs when we change the code, and we could push a new version of the docs whenever a new version of the package(s) are released (we'd also need a formal release process as part of this).

@chalin:

And we have living examples and docs with travis run tests and checks. In particular, we run both component tests and E2E tests (using the new build system), as shown in this Travis log.

These might be good to make sure everything continues to work, but I don't how useful it is for an average Joe/Jill user who is trying to learn the system.