Skip to content

Commit

Permalink
feat: add resources for documentation driven development
Browse files Browse the repository at this point in the history
  • Loading branch information
shanejonas committed Jan 31, 2019
1 parent 4b2e8f0 commit 94c6214
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 10 deletions.
14 changes: 9 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

> This document is inspired by [elasticsearch/CONTRIBUTING.md](https://github.com/elastic/elasticsearch/blob/master/CONTRIBUTING.md)
Adding a `CONTRIBUTING.md` to a github repository enables a link to that file in the pull request or create an issue page. This shows potential contributors how to make a meaningful impact on the project. Contribution guidelines save time and hassle caused by improper pull requests and issues. You can learn more about the features that are enabled by github when this file is present [here](https://help.github.com/articles/setting-guidelines-for-repository-contributors/)

## How to contribute

There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, [submitting github issues](https://help.github.com/articles/creating-an-issue/), bug reports, feature requests and writing code.

## License
Expand Down Expand Up @@ -31,13 +35,13 @@ For small documentation changes and fixes, these can be done quickly following t

### Cloning (or forking) the repository

First off, you are going to need your own copy of the repository. You can find help on how to fork a repo [here](https://help.github.com/articles/fork-a-repo/).
First off, find help on how to fork a repo [here](https://help.github.com/articles/fork-a-repo/).

### Submitting your changes
### Submitting changes

1. Review & Test your changes
1. Review & Test changes

If it's code: make sure you test it. If it's documentation: make sure you view it in a Markdown viewer or the like.
If it's code: test it. If it's documentation: make sure to view it in a Markdown viewer or the like.

2. Commiting

Expand All @@ -51,7 +55,7 @@ Make sure you've signed the repository's Contributor License Agreement. We are n

4. Submit a pull request

Push your local changes to you forked repository and make a pull request. Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines for naming Github pull requests and what to put in the body.
Push local changes to you forked repository and make a pull request. Follow the [Convention Commits](CONVENTIONAL_COMMITS.md) guidelines for naming Github pull requests and what to put in the body.


## Building
Expand Down
27 changes: 22 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,18 @@
# Pristine

Pristine is an open source repository in its original condition. It is meant to be a starting point and a place to find resources to augment your own open source repositories.
Pristine is an open source repository in its original condition. It's goal is to be a starting point for open source repositories wanting to follow Documentation Driven Development. It is also a place for existing projects to find resources to augment current documentation.

## Documentation Driven Development

There are many ways to drive development but with open source specifically, starting at the README gives a middle ground between technical specifications and non-technical. This promotes open source contribution and engagement.

> By the same principle a beautifully crafted library with no documentation is also damn near worthless. If your software solves the wrong problem or nobody can figure out how to use it, there’s something very bad going on.
- [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) by Tom Preson-Werner

## Getting Started

To get started, you will need a [fork of the repository](https://help.github.com/articles/fork-a-repo/). Then you can edit this file and delete everything above this line.
To get started, [fork](https://help.github.com/articles/fork-a-repo/) or [duplicate](https://help.github.com/articles/duplicating-a-repository/) the repository. Then edit this file and delete everything above this line.

---

Expand All @@ -14,8 +21,8 @@ To get started, you will need a [fork of the repository](https://help.github.com
Using conventions and specifications make it easier to:
- build and use composable tools
- ease onboarding
- promote contribution
- promote issue and feature discussion
- promote contribution and engagement
- promote issue and feature discussion on github itself

### Contributing

Expand All @@ -25,7 +32,17 @@ How to contribute, build and release are outlined in [CONTRIBUTING.md](CONTRIBUT

#### Docker:

Docker is used as a building block. Here are the resources you need to get started and install docker:
Docker is used as a building block. Here are the resources needed to get started and install docker:

- [Install Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/)
- [Install Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/)

#### Resources

- [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [pengwynn/flint](https://github.com/pengwynn/flint)
- [Working Backwards](https://www.allthingsdistributed.com/2006/11/working_backwards.html)
- [Literate programming](https://en.wikipedia.org/wiki/Literate_programming)
- [Hammock Driven Development](https://www.youtube.com/watch?v=f84n5oFoZBc)
- [Inversion and The Power of Avoiding Stupidity](https://fs.blog/2013/10/inversion/)

0 comments on commit 94c6214

Please sign in to comment.