search

jstransformers / boilerplate

Boilerplate for JSTransformers. See the Wiki for documentation...
https://github.com/jstransformers/boilerplate/wiki
MIT License
5 stars 1 forks source link

Move documentation to the Wiki #21

Closed RobLoach closed 9 years ago

RobLoach commented 9 years ago

Moving documentation to the wiki will allow us to change docs without affecting child projects.

https://github.com/jstransformers/boilerplate/wiki

Perhaps we even turn jstransformer-boilerplate into an actual project with working implementations of .render(), .compile(), etc.

ForbesLindesay commented 9 years ago

I think that documentation needs to be visible front and centre because it explains what this repo is.

I'm not sure I understand how changing it affects child repos?

TimothyGu commented 9 years ago

I believe this commit prevents leaking boilerplate setup instructions to jstransformers. However, I agree with @ForbesLindesay that there should be a link somewhere to the wiki now that it is not on the front page.

RobLoach commented 9 years ago

What @TimothyGu said... I've updated it with A BIG DOCUMENTATION HEADER LINK AT THE TOP.

You guys particular about the copy in there?

ForbesLindesay commented 9 years ago

That still has potential to accidentally leak though?

TimothyGu commented 9 years ago

Another way to solve this is by putting the wiki link into the repo description, which hopefully will be hard to miss.

ForbesLindesay commented 9 years ago

I can't help but think that all of these options are worse than what we have at the moment.

Currently it's super obvious when you view the readme and super clear that you're expected to remove it before publishing your module.

RobLoach commented 9 years ago

Currently it's super obvious when you view the readme and super clear that you're expected to remove it before publishing your module.

https://github.com/jstransformers/boilerplate/tree/wiki#see-the-boilerplate-wiki-for-usage-instructions I'd consider a big h1 link pretty obvious. Perhaps we keep minimal listed instructions, but push them forwards to the wiki documentation? Having the more detailed stuff in the wiki does seem appropriate.

What about something like..........

# JSTransformer Boilerplate

Use JSTransformer Boilerplate to create and update transformers.

1. Visit [the Boilerplate Wiki](https://github.com/jstransformers/boilerplate/wiki) on how to use this project
2. Remove this top notice from any transformers

# jstransformer-foo

[...]
ForbesLindesay commented 9 years ago

That would be fine by me :)