[EPIC] Major update to README and documentation #576

cdrage · 2016-02-25T21:46:45Z

Please be kind with commenting :), still a WIP. Going to be updating as I go. Just want to make this progress public.

It's HIGHLYYY recommended you view this through: https://github.com/cdrage/atomicapp/tree/update-readme-2 instead of looking at raw .md files. Gives you a better perspective on the new docs.

Left to do:

Guide on using atomicapp cli bare metal
Guide on using atomic cli on atomic host
List of all current features you can use in Nulecule file
Persistent storage doc

bexelbie · 2016-02-26T06:29:37Z

If no one objects, I have put these changes in an etherpad: http://etherpad.osuosl.org/aad

This way we can easily make edits and notes. The files are all there with bold titles between them.

cdrage · 2016-02-26T14:53:43Z

@bexelbie awesome, i'll work on it there / make changes / update the github as I go.

only problem is that unless it's synced with github we can't see the changes as to what it looks like on github itself. but this will be easier to edit and all :)

bexelbie · 2016-02-26T15:06:50Z

Cool. My thought was that after 4-5 people had trawled through it, we would move back to using hte PR.

I may not get to it until Tuesday :(

dustymabe · 2016-02-26T21:44:58Z

README.md

+
+__Running Apache on Docker:__
+```sh
+▶ sudo atomicapp run --provider=docker projectatomic/helloapache


for these example commands let's make them compatible with the Atomic cli notation - I think with atomic cli we have to put the image name first and then the option after right?

so we should changes these examples to put the --provider= after the image name. Does that seem like the right thing to do?

dustymabe · 2016-02-26T21:57:42Z

docs/start_guide.md

+
+__Graph__ is the most important section. In here we will indicate all the default parameters as well as all associated artifacts.
+
+```yaml


I would add params: right below this line. so that the reader knows exactly where this text came from without having to fish for it.

Thanks - and this is a test message so please ignore #dotests

One more test #dotests

dustymabe · 2016-02-26T22:08:53Z

docs/start_guide.md

+
+Similarly, the kubernetes provider uses both `$image` and `$hostport` variables for pod deployment.
+
+### ~/helloapache/answers.conf.gen


answers.conf.sample - gen is the file that gets generated on run.

dustymabe · 2016-02-26T22:15:27Z

@cdrage - great job and thanks for taking an initiative on the docs! I look forward to the updates to fix the TODOs.

jberkus · 2016-02-27T00:38:28Z

The funny thing is that this line is the single most significant thing in the new readme:

For a list of already packaged examples, visit the [nulecule-library](https://github.com/projectatomic/nulecule-library) repo.

Previously we had a link to this repo: https://github.com/projectatomic/nulecule/tree/master/spec/examples/template

... which, of course, has no examples. I never knew about nulecule-library; we didn't link to it before.

More to come!

jberkus · 2016-02-27T01:05:22Z

README.md

+  - OpenShift 3
+  - Marathon (Mesos)
+
+Providers represent various deployment targets. They can be added by placing the artifact within the respective in `provider/` folder. For example, placing `deploy_pod.yml` within `providers/kubernetes/`. 


The examples in nulecule-library have the providers directly in the artifacts directory. Where is this provider/ directory supposed to be?

We should update it to say artifacts like all of our examples use. In truth you can use any folder name, but here we should use ./artifacts.

That's my bad, it's suppose to be artifacts >.>

jberkus · 2016-02-27T02:00:52Z

The startup guide should explain that, if you're running these on your desktop and not in the ADB or similar, you'll need to run a lot of the commands using "sudo", such as all of the "atomicapp" commands.

dustymabe · 2016-03-02T21:50:03Z

README.md

+7. [File handling](docs/file_handling.md)
+8. [Specification coverage](docs/spec_coverage.md)
+9. [Contributing](CONTRIBUTING.md)
+10. [Dependencies](docs/requirements.md)


I don't know where these links fit in - they link to other files but there are also sections below for most of the same headings. Are the sections below supposed to be there?

Maybe the best thing would be to keep it the way it is but move it somewhere else within this file. I see value I just don't think where these links currently sit is the best place in the file.

Hmm. I wanted to follow something along the lines of how docker and kubernetes do their documentation. i quite like that there is an index that shows direct links to the files I'd like to view.

having it near / at the top of the readme.md would be great.

You're right about the headers (some of them are duplicate headers in the readme that link to the same doc)

Yeah right now it just looks confusing. I'm not saying we shouldn't have the links, but we should clear things up a bit.

cdrage · 2016-03-03T20:47:12Z

I have updated based on your comments @dustymabe . The major difference being start_guide.md comments.

dustymabe · 2016-03-03T21:37:15Z

README.md

-```
-docker build -t [TAG] .
-```
+## Documentation



Maybe say this:

This README contains some high level overview information on Atomic App. The detailed documentation for Atomic App resides in the docs directory. Links to each section have been conveniently listed below:

dustymabe · 2016-03-03T21:39:00Z

ok @cdrage.. I had just one final comment. I'm good to go, although I know jberkus may have had some more stuff he wanted us to add.

either way we can keep adding to it in new PRs if we want to go ahead and get this in.

jberkus · 2016-03-04T01:00:03Z

I think this is fine for a first version. We'll have more, but then we'll always have more.

cdrage · 2016-03-04T15:21:18Z

Hey @dustymabe

I've updated it again based on your comments (only inclusion is your comment about the index / links)

With the exception of a section on how to use the answers.conf file (I'll add this in a later PR / section), it's good for merging.

dustymabe · 2016-03-04T18:01:11Z

cdrage merge away.

[EPIC] Major update to README and documentation

cdrage · 2016-03-07T06:02:45Z

✨ Wooooo! :) Thanks everyone for the docs reviews!

cdrage force-pushed the update-readme-2 branch 8 times, most recently from f50eece to 2c786ca Compare February 26, 2016 21:41

dustymabe reviewed Feb 26, 2016
View reviewed changes

cdrage force-pushed the update-readme-2 branch from 2c786ca to e3cd535 Compare February 26, 2016 21:56

dustymabe reviewed Feb 26, 2016
View reviewed changes

cdrage force-pushed the update-readme-2 branch from e3cd535 to cfdbd7c Compare February 26, 2016 22:01

dustymabe reviewed Feb 26, 2016
View reviewed changes

jberkus reviewed Feb 27, 2016
View reviewed changes

cdrage force-pushed the update-readme-2 branch from cfdbd7c to d0b11ef Compare February 29, 2016 16:57

cdrage mentioned this pull request Mar 2, 2016

ReadWrite no longer a parameter for Persistent Storage. #587

Closed

dustymabe reviewed Mar 2, 2016
View reviewed changes

cdrage force-pushed the update-readme-2 branch from 663c8c6 to 8a030ea Compare March 3, 2016 20:45

dustymabe reviewed Mar 3, 2016
View reviewed changes

Major update to README and documentation

a4815ec

cdrage force-pushed the update-readme-2 branch from 8a030ea to a4815ec Compare March 4, 2016 15:19

cdrage added a commit that referenced this pull request Mar 7, 2016

Merge pull request #576 from cdrage/update-readme-2

ce03e52

[EPIC] Major update to README and documentation

cdrage merged commit ce03e52 into projectatomic:master Mar 7, 2016

cdrage deleted the update-readme-2 branch March 7, 2016 06:02

This was referenced Mar 7, 2016

Moved Developers to CONTRIBUTING.md #543

Closed

Move the Developers section from README to CONTRIBUTING #542

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EPIC] Major update to README and documentation #576

[EPIC] Major update to README and documentation #576

cdrage commented Feb 25, 2016

bexelbie commented Feb 26, 2016

cdrage commented Feb 26, 2016

bexelbie commented Feb 26, 2016

dustymabe Feb 26, 2016

dustymabe Feb 26, 2016

cdrage Feb 29, 2016

dustymabe Mar 1, 2016

dustymabe Mar 1, 2016

dustymabe Feb 26, 2016

dustymabe commented Feb 26, 2016

jberkus commented Feb 27, 2016

jberkus Feb 27, 2016

dustymabe Feb 27, 2016

cdrage Feb 29, 2016

jberkus commented Feb 27, 2016

dustymabe Mar 2, 2016

dustymabe Mar 2, 2016

cdrage Mar 3, 2016

dustymabe Mar 3, 2016

cdrage commented Mar 3, 2016

dustymabe Mar 3, 2016

dustymabe commented Mar 3, 2016

jberkus commented Mar 4, 2016

cdrage commented Mar 4, 2016

dustymabe commented Mar 4, 2016

cdrage commented Mar 7, 2016


		__Graph__ is the most important section. In here we will indicate all the default parameters as well as all associated artifacts.

		```yaml


		Similarly, the kubernetes provider uses both `$image` and `$hostport` variables for pod deployment.

		### ~/helloapache/answers.conf.gen

[EPIC] Major update to README and documentation #576

[EPIC] Major update to README and documentation #576

Conversation

cdrage commented Feb 25, 2016

bexelbie commented Feb 26, 2016

cdrage commented Feb 26, 2016

bexelbie commented Feb 26, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dustymabe commented Feb 26, 2016

jberkus commented Feb 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jberkus commented Feb 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdrage commented Mar 3, 2016

Choose a reason for hiding this comment

dustymabe commented Mar 3, 2016

jberkus commented Mar 4, 2016

cdrage commented Mar 4, 2016

dustymabe commented Mar 4, 2016

cdrage commented Mar 7, 2016