Should there be a docs project?

Is there a place we can contribute and co-edit docs and other learning resources other than the Discourse? If there isn’t, should there be? If so, should this be a Github project? Should it be the Github Roots wiki? Should it be something else?

The documents at are great starting points, but I already see a dozen places in Roots 101 where I want to add (or want) a more detailed explanation, more specific instructions, or basic examples for my own benefit. In some cases I need to learn more about Roots before I can do that. I’m assuming the information would be useful for others getting into the Roots environment.

I’m also building PNGs and PDFs of the elements on the default templates, how they’re nested, IDed, and classed. Those might be useful for people getting a handle on the basic page structures Roots builds as a first step to understanding how to customize them. I’m sure other places could benefit from diagrams might be helpful additions to some of the docs.

IMHO: I think there should be a place where the Roots community can work on building a coherent, organized set of docs and that Discourse doesn’t lend itself to that kind of coherence or organization. I don’t know which of the non-Discourse options is best.

Docs used to be bundled with the theme but they were removed with the 6.5 update. I assume one reason for that is because a lot has changed and they need to be reworked. They are probably working on the docs right now.

But, you are right, there should be an easy way for users to contribute to the documentation just like there was pre-6.5.

GitHub Wiki would be a good solution. A couple of others I think are neat:

No one ever contributed to the documentation when it was on GitHub (originally was a wiki, then as the docs/ folder in the repo)

I’d like to keep the documentation on We’d be more than happy to accept posts to add to the site. We’re using grunt-wordpress + Markdown to publish posts, so if you want to write up a private gist in Markdown and send it over we can put it up.

If you’re interested in contributing some documentation, please start a discussion prior to writing either on here or in an email to me.

I’ve started outlining the high points and will put it up here when it starts to gel. I’ll probably draft sections for my own benefit even if it never goes any further.

I’m thinking Roots 100–like Roots 101, but with more scaffolding for learners. I’m thinking multiple parts based on the first parts of Roots 101 with more details, command lines for Lin(apt/rpm/yum)/Mac/Win where applicable, fill in missing steps (like “Install node.js” between the first and second sentences), etc. Building an effective development environment, pros and cons of different environments (not so much debate and identifying the issues so people can decide which they want to use).

As I learn more about Roots, I can see wanting deeper technical discussions, when I get there, maybe some of the other docs on will cover me or maybe I’ll want to expand parts of them. I think there are some ideas in other posts on the Discourse too. I’m still getting a handle on my development environment, basic setup, and basic workflow, so that’s what I’m focused on learning and capturing both so I don’t forget and to help others getting started.

Anyone who wants to contribute topic ideas, please do. I can work them into the outline. I have access to Linux apt (Ubuntu) and Windows, but will need input on the other command lines when I get there. I may put the work up on Github or somewhere temporarily to make that cycle easier.

I do hope that the development of the docs can keep apace with the rest of the development of Roots. I, for one, am still slightly confused about the Theme Templates, Theme Wrapper and Extending Templates sections of the “Roots 101” page and the “Introduction to Roots Theme Wrapper”. For example: Which templates go in the root directory and which in the /templates/ directory? Templates with names like those of ordinary wordpress theme files, will those behave normally with Roots or not (I presume not)? Might it help to use a documentation style that is very similar to that of the Wordpress Codex?

Have good post about templates in only (brutaly) closed discusion “Development using Roots” by @iagdotme.

The Github contributions to docs were few and far between, which is why the wiki was removed. The move from a Google Group to Discourse should also help documentation, as it’s much easier to share tips, support and code here.

@dylan I mentioned in my wrapper post that the Roots Wrapper starts and finishes with the standard WordPress Template Hierarchy. This means that all of the standard WordPress templates will work as intended. The only change is that the templates will not need to call the header, sidebar and footer because the base file does this for them.

Hopefully the above diagram will help you visualise it.

To select the $base file Roots simply prepends the $template file with base-, so you get base-{$template}.php if it exists, base.php if it doesn’t.

The WordPress templates go in the theme root, as they would with any other theme. The base files go in the root, but you could move them with a minor change. The templates folder is just a means of separating the code into reusable chunks; it has nothing to do with the wrapper (save for the sidebar being chosen in the same was as our base file). Any of the files in templates can be moved if you update the references.

can you upload again the pic