Need docs

[aweiteka]

I suspect one of the reasons atomicapp is confusing to people is we don't have docs. Needed:

1. Create a docs directory in this repo
2. Create initial docs
3. Require each PR to contribute to docs

[cdrage]

Despite projectatomic/nulecule being a spec repo, it has examples specific to the python implementation.

As a newcomer it's confusing that I have to look projectatomic/nulecule at the same time as atomicapp. As well as the fact that there could me more than one implementation in the future, could we have examples in this repo too? A good alternative would instead of having the examples in projectatomic/nulecule but have them here and have the specification link to them.

[bexelbie]

One idea would be to merge the two repos. If this is a reference implementation, it could live with the spec.

If we don't do that, we need to decide what an example in both repos actually looks like/means.

[goern]

in any way we (maintainers) need to be more careful about the PR we merge and try to work with the contributors to increase the PRs we get.

[goern]

@bexelbie I would continue with the strict separation of SPEC and REFIMPL, as we have one fast moving repo and one that is basically unchanged since half a year.

[bexelbie]

@goern that is fine with me, however we should think about how to address this from a usability perspective as pointed out by @charliedrage

[jasonbrooks]

I too have been confused about the atomicapp examples living in nulecule, rather than in atomicapp.

[vpavlin]

I understand the confusion. On the other hand, we need to have some examples in the spec repo so that people can easily find it. Any suggestions how to distinguish what qualifies for the spec example and what is better for implementation example?

[bexelbie]

@vpavlin I feel like the differentiation is this. Examples that strictly follow the spec belong in Nulecule. Examples that use a non-spec extension belong in the implementation repo.

If atomicapp is never going to vary from the spec, we need to think about why it is separate from the spec. I respect @goern's assertion that we shouldn't combine a fast moving implementation with the slower changing spec, however I am not sure exactly how this presents a problem logistically.

Perhaps we should generalize the documentation in the Nulecule repo to just discuss how the spec was used to create various files. Then in the atomicapp repo we discuss how we packaged and used the examples?

[vpavlin]

I actually agree with @goern that as long as the spec is not represented by code (instead of text) and as long as we expect other implementations, Nulecule and Atomic App should be kept separately.

OTOH, I agree with you that if the examples don't comply to the spec, they shouldn't live in a spec repo but rather in a Nulecule-examples repo. Maybe this is where we should introduce new rule to a contribution guide - if your PR is changing the spec, you need to also change the examples.

[dustymabe]

+1 to keeping them separate as we really want the spec to be adopted by the masses and it has a better chance of doing that if there isn't one company/interested party tied to it. In the end if the spec was widely adopted but our implementation of it wasn't then I would still consider it a win.

I think the examples should live in the atomicapp repo and there should simply be a pointer to them from the nulecule repo. I would move them and then put a readme in the examples directory in nulecule that is a link to the new location.

[bexelbie]

@dustymabe so no examples at all in the nulecule repo? Not even compliant ones?

[cdrage]

I agree with @dustymabe is that in order for our spec to be more widely used it should be open to interpretation as to what language / implementation to use. With examples to atomicapp already in the Nulecule spec it may give bias as to what implementation to use rather than thinking of ones own. Personally, I would like to see something in Go and Rust also gain momentum.

The README.md of projectatomic/nulecule is excellent and the example in that is concise and gives a great explanation as to how to deploy Nulecule (despite the end-part showing that it's an atomicapp example, it gives a great overview on what the implementation format should be, in atomicapp's case, yaml). However, a lot of the atomicapp documentation is heavily in projectatomic/nulecule.

Even the "how to get started" for atomicapp is in there, which doesn't really make sense, as well as the examples.

I believe it would be best to have getting started, examples and contributing guides that directly reference the implementation put into it's corresponding implemetation, and the spec just have specifications of how the overall implementation is supposed to be ran / developed.

[dustymabe]

@charliedrage very well said.

[goern]

@charliedrage aint the only implementation specific references in the nulecule spec examples to FROM lines of the Dockerfiles and the directory layout? If we want to get rid of these, we need to provide a better "getting started with the spec's usage" chapter and completely loose the link to a reference implementation. I dont see the advantage of that. We need to educate people how to use the spec, why not with examples using the reference implementation, that seems to be a good practice.

[aweiteka]

Technically this issue is resolved based on the initial list. Now we need comprehensive docs and good docs. :)

[dustymabe]

Several things here:

1 - as @aweiteka pointed out the initial list has been done
2 - the examples have been broken out into nulecule-library github repo

we still need more docs and an uber example but that will come. Closing this issue