[Docs] Working Guidelines

[thedavidprice]

edited on 5/18: added information about Contribution and Development documentation

Two Contexts for Docs: Contributing and Developing

✏️ "Contributing" Docs: Located in the Redwood Packages Repo

These docs are located in the Framework repo redwoodjs/redwood and contain content to assist in contributing to Redwood packages. In general, they may be more straightforward explanations, technically heavy, and written for individuals with more experience. However, as a best practice for collaborative projects, these docs should still provide a Vision + Roadmap and information about who is the project point person (or lead).

• Framework root dir README (owned by Tom as the master project Vision doc)
• Also in root dir, a CONTRIBUTING doc that provides general information and a directory of the contributing docs for each package
• Each package will have a contributing README in it's root

README Stub

For an example of of package README, see this one for the Web package. Here's the general outline

# PackageName

<!-- toc -->
- [Purpose and Vision](#Purpose-and-Vision)
- [Package Lead](#Package-Lead)
- [Roadmap](#Roadmap)
- [Contributing](#Contributing)
- [FAQ](#FAQ)

## Purpose and Vision
Summarise the project's values, purpose, and aspirational vision.

## Package Lead
Identify the decision maker and/or go-to for questions.

## Roadmap
Similar to Purpose and Vision, but more concrete, comprising near-term priorities and long-term goals.

## Contributing
Explains how to contribute by addressing the following three points:

1) Core technologies a contributor should be a familiar with.
2) How this package fits into the Redwood Framework, if it depends on other Redwood packages, etc.
3) The structure of the package and/or an explanation of its contents.

## FAQ

Answers to frequently asked questions.

✏️"Developing" Docs: Located in the Redwoodjs.com Repo

These docs are located in redwoodjs/redwoodjs.com repo and are displayed on the Redwood website. The purpose of these docs is to help individuals develop applications using Redwood. There are three types of Developing docs:

⚡️The Redwood Tutorial: this is a standalone doc and serves a specific purpose as an introduction to Redwood, an aspirational roadmap, and an example of developer experience. As such, it's distinct from the categories below although most similar to the Cookbooks.

@cannikin created and maintains the Tutorial.

1) Cookbooks

Tutorial-style content focused on a specific problem-solution. Most often these have a beginner in mind (if not, they should indicate 'advanced' or 'deep-dive', etc. in either the title or intro). Cookbooks may include some explanatory text as asides, but this should not be the majority of the content.

2) Guides

Guides are for "how-to" specific content. They are similar to Cookbooks in that they are problem-solution oriented. However, they are more direct and to-the-point. The focus is "getting something done" much more than any kind of "learning journey".

3) Reference

These include API, Config, CLI, etc. They should be information-oriented, accessible, comprehensive, and well structured to make content findable. We've all experienced great API documentation. That's what we want this section to be in the future.

(Bonus) Explanation

There is another type of documentation that focuses on conveying understand (verses learning or problem-solving). For Redwood Docs, this is not a specific category but is included (when needed) as a call-out section. A great example from the Tutorial is Side Quest: How Redwood Works with Data.

👉 Guidelines

• cross-linking: although Contributing and Developing docs are displayed in different locations, they most definitely should be linked and referenced as needed to redirect readers. E.g. It's appropriate to have a "Contributing" doc on redwoodjs.com that's context-appropriate, but it should link to the Framework CONTRIBUTING doc.
• findability: docs should follow general SEO practices regarding menu links, Titles, Headings, and included copy -- use keywords that will help people find what they are looking for when browsing menus and using Search.

Misc Info

Different docs, different handling/cases

see: https://www.divio.com/blog/documentation/

1. Tutorials
2. How-to Guides
3. Explanation
4. Reference

For example about what we’d like to do for “Reference”, see CLI doc Issue #322

[weaversam8]

Some helpful inspiration we can reference from Storybook, a project with great documentation about documentation:

• Storybook's guide for triaging issues
• Storybook's style guide for writing good documentation ⬅️ this seems helpful to have, to have a consistent tone and voice

[jonniebigodes]

also the gatsby documentation approach overlapping with the storybook would make a excelent base for documentation. More specifically docs contributions community contributions and their style guide

[thedavidprice]

@jtoar I've updated this Issue (see original comment). Reactions and/or changes?

[thedavidprice]

Also, I've added a GH Project to help keep track of everything in motion here: https://github.com/redwoodjs/redwood/projects/3

[jtoar]

This looks great! :+1: A few things to consider adding:

• Another guideline could be that docs should be "aware" of each other--redirecting the reader when appropriate.
• A note on separation: that we think this level of separation (redwoodjs.com vs repo) is warranted and since the criteria dividing the two kinds of docs is very clear (the change in audience, developing vs contributing), that there won't be any confusion.
• We could list Side Quest: How Redwood Works with Data as an example of what would qualify as a divio explanation doc.
• Should we list "clarifying the place of explanation docs" as an outstanding todo?
• I remember you mentioning this: to help make things more findable, be sure to include keywords. Is there more to say about this?
• The tutorial isn't mentioned much--maybe some criteria for updating the tutorial. Is this something the core team will primarily do? I.e. is it preferable for contributors to add new cookbooks/guides/references than tutorial updates or suggestions?

Those are my thoughts right now but I'll add more as they occur to me.

[thedavidprice]

@jtoar thanks! I've updated and added based on your comments.

re: "Explanation" docs, I think this will emerge over time. Most likely these will just go in "Guides" section. If we start to outgrow then we'll re-org.

[jtoar]

@thedavidprice bringing this up again in light of #3485