search

openzipkin / openzipkin.github.io

content for https://zipkin.io
https://zipkin.io
Apache License 2.0
38 stars 63 forks source link

Define a process for dumping things here #109

Open codefromthecrypt opened 6 years ago

codefromthecrypt commented 6 years ago

After we elaborate certain things like designs etc, we could dump them here. We also have some things in google drive we could consider dumping here.

I would love to have a reasonably easy way to add markdown about a meetup that occurred, like notes from it. It would be something we can add after it is over, so thrashing the content isn't likely.

@openzipkin/devops-tooling ?

codefromthecrypt commented 6 years ago

PS context is that google docs aren't addressable in china. office 365 is still dunno doesn't seem culturally well used in open source. etherpad is pretty rad, but not a great offline repo.

etherpad -> stable -> pull request here seems good enough. and indexing could happen as well.

if we later want to make some docs and such, should be easy enough to copy/paste again!

see also: https://groups.google.com/forum/#!topic/zipkin-dev/6ibgOXDngwE

abesto commented 6 years ago

Methinks the doc site could definitely use a betterer, easier-to-edit format. First thing that comes to mind is https://readthedocs.org/.

I notice we're talking about two kinds of contents here: one is notes / proposals dumped into a “knowledge base” another is stable, user-facing documentation. readthedocs looks promising for the latter, unsure if it's a good fit for the former.

Short term: dump the things into pages/, and link to them directly as needed? We can also set up a page that automatically lists all pages with a given tag or under a given path, but let's I think not invent this particular wheel.

devinsba commented 6 years ago

Mentioning that there are actually 2 different kinds of docs we are talking about brings to mind Architectural Decision Records. There have been teams at work who have had success using them to work through changes and document the design process. I wonder if this is a good avenue for the design notes type of discussion and documentation.

I've previously looked at https://github.com/npryce/adr-tools to facilitate this on my team. We haven't attempted it yet though

codefromthecrypt commented 6 years ago

love the discussion here