Contributor documentation kick off

[gianarb]

Expected Behaviour

IMHO this is a P2 because I feel blocked from writing documentation for contributors until we don't have a place for it.

As a potential contributor, I want to be able to get my own documentation, because maybe I am a user as well for Tinkerbell but I have different needs.

Recently worked with bird, and I know, the site has its style that comes directly from the 80s but I like how clearly it brings me to my journey as a user or as a contributor.

This is an example of this issue that I would like to see documented in the "contributor" section tinkerbell/tink#177 . A lot of the documentation as I wrote there needs to be in the code itself, but from the website, we should point the contributor in the right direction explaining more high level what the testing framework is designed for and what it provides.

@DailyAlice what do you think?

[DailyAlice]

I definitely like this! @gianarb

More concretely, are you thinking of making something like the content of https://pkg.go.dev/github.com/tinkerbell/tink@v0.0.0-20200714130438-0100e535bd94/test/framework?tab=doc a part of the documentation?

And to extend the Bird example -
"User Guide" - current Tinkerbell website docs (which are definitely more user-focused currently)
"Coder's Doc" - the Tinkerbell docs generated in the link above (more developer/contributor focused)

We can definitely name the two halves however we want, I just wanted to make sure I was understanding correctly.

[gianarb]

Hello @DailyAlice !
The documentation you linked is the one used from a developer when learning a framework in the act of embedding code we wrote as part of Tinkerbell in their codebase. It is important and it applies to something like:

• Client Libraries (because those are used by other developers in the act of extending Tinkerbell).
• Testing Framework (the one you linked) that are used when writing tests.

But it is not what I have in my mind for what concerns the Coder's Doc, I think a better name is Contributors Doc because the end goal for it should be to help contributors not wasting time on a problem other contributors solved in the act of writing code, troubleshooting and releasing Tinkerbell.

A possible TOC for Contributors Doc will be:

• How CI works
• How to write e2e tests from Tinkerbell (with a link to the framework you linked probably but also more)
• How to make a release
• Golang style guide for the project (https://thanos.io/contributing/coding-style-guide.md/)
• Troubleshooting Tink GRPC server
• Triaging runbook (@mrmrcoleman is writing it down)
• ...

Topics that users do not care about, but people who want to help will care. I think the way you are picturing Coders based on what you linked is what I see as a user. The Tinkerbell's user will always interact with an API, it means that client libraries, as well as CLI, are part of the documentation that users care about because those are just different ways to use Tinkerbell.

[DailyAlice]

Okay, thanks, I see what you mean.

Your TOC looks like an excellent starting point. I think good enough to at least start trying to research and start writing those things down.

If you have any content for any of those topics, feel free to drop them here or send them my way. I'll also start researching, asking around, and collecting all the things.

[rainleander]

Is there anything I can do to help resolve this in the next week?

[gianarb]

I don't know how to do it, my expectation is be able to implement a table of contents like:

- Contributors Docs
    - Go
    - Continuous Integration
    - Code review
    - Pull request lifecycle

if you can help me to find the right place where I can write those contents I happy to bootstrap them

[rainleander]

if you can help me to find the right place where I can write those contents I happy to bootstrap them

Started the file on #143 with your requested ToC. Let me know how else I may help.

[gianarb]

We have this!