☂️ Documentation

[rzig]

I think it makes sense to have an issue for documentation-related tasks since the website is up now. Here's a couple things I was thinking would be good to add as a start:

• Install and update instructions
• Getting started that uses rome init instead of echo - possibly a two tracks, one for new projects one for existing
• Command documentation within the command definitions themselves (packages/@romejs/core/master/commands)
• Add command docs and examples to website for all commands - if we can automatically pull from the command definitions that would be great
• Linting behavior - may want to hold off until this is finalized
• Usage with popular tools, ie React, Hapi

After writing the install and getting started, I'm thinking it makes sense to break the remaining up into a section of "Everyday Rome" which covers the most commonly used commands in depth with examples, a section of "Rome and Frameworks" which covers any framework-specific steps, and a section of "Rome Commands" which covers every option on every command, not necessarily with a ton of examples.

I'll try and work through some of these this week, but any help would be appreciated - if anyone has ideas on other things that would be valuable to add, that would be great!

[zinyando]

I'm interested in helping out with this. We need to come up with a strategy on how to tackle what is ready to be documented.

[rzig]

I will open a PR today with the first two items.

As for the remaining items, what's your thought on those? I'm thinking we ought to start with docs for run and test since those probably won't change significantly and will be some of the most commonly used commands. I'm hesitant to add too much to other commands such as lint since those will probably have significant changes in behavior.

[zinyando]

I think we can start documenting the following sections under the CLI --help command

Source Code Commands
Code Quality Commands
Project Management Commands

I don't think the function of the commands themselves will change much. The aim would be to document the basics of how things work instead of letting people struggle to figure things out on their own. The docs can be basic to start, we can add more flesh to them as time goes. What do you think?

[sebmck]

Deferring to #496.