Style Documentation site

[TheWebTech]

In order for people to be able to use CrankShaft there needs to be documentation explaining how to use it.

Let's talk about what the best way to implement this is.

If we were to do a GitHub pages site, all of our code would have to be precompiled since HubSpot can't process it there.

We may be able to use a Developer sandbox site for Demos of compiled code. Chad Pierce and I discovered you can share access to a developer sandbox site. So a possible idea is use a github pages site for the actual documentation site, and the sandbox site to show the output of code examples. (sandbox sites can't have domains without being upgraded.)

One of the goals of the documentation site should be that it should be able to be open sourced, so people can contribute. It can also be simple. I'd be fine with using a github pages theme and someone can design something cool later.

Thoughts?

[TheWebTech]

[TheWebTech]

https://github.com/lord/slate

Slate does seem like an okay fit.

It's design for API use, is there any reason it should/shouldn't be used for a bootstrap/foundation like framework?

[TheWebTech]

I set up the github repo to use github pages it pulls from the /docs/ folder. If anyone wants to lead the charge on this that would be really really awesome. Figure out if you want to use Slate for the docs. If so, see what the next step is to integrate it. Live site is: https://thewebtech.github.io/CrankShaft/

I will work on getting a domain name once we get some actual content for it.

[ajlaporte]

Another Alternative could be: https://github.com/thomasreinecke/git-playbook

[TheWebTech]

That one's cool. I like the look of it.

Here is a list of some options that are directly integrated with github (meaning github automatically handles most of the setup) https://pages.github.com/themes/ We don't have to go with one of their options, we can go any direction. Just listing as those may be a good starting point if we want to just get something simple up, then find something better when we reach a point that we need better.

I have no real experience doing anything with github pages nor these documentation frameworks. So I'm open to anything. I do want to try to pick something quickly so we can run with it and have something simple to begin. No reason we can't change later. Whatever tool I think markdown is important and would also make it easier to revamp the site at a later time.

[joneichler]

I think the Cayman theme would be a good choice https://pages-themes.github.io/cayman/ At least as a starting point. Also, I think Playbook looks great.

[TheWebTech]

Swapped to cayman to get a feel for it https://thewebtech.github.io/CrankShaft/

made a separate issue for discussing domain name. #47

[joneichler]

I'll finalize the logo and can tweak the cayman theme to match the color scheme

[TheWebTech]

Did some further setup of cayman theme.

Any styles can go in docs/assets/css/style.scss

[TheWebTech]

Just adding this because I just read it and I thought there was a lot of good info related to the process we've been going through with the docs.

You can have the best open source project in the world but, if it doesn’t have good documentation, chances are it’ll never take off.

https://css-tricks.com/front-end-documentation-style-guides-and-the-rise-of-mdx/

So if you’re thinking, I don’t want to work on the documentation site, because it’s not as important, you’re wrong. Both the framework itself and the documentation site are equally valuable and necessary. Only the most invested of us in the framework could use it without the documentation, and without the documentation we can't as easily understand why it's built the way it is. So we can't intelligently improve the framework without it.