Basic Getting Started Documentation #122
Conversation
thescientist13
added
the
website
| To install greenwood you'll need all the [prerequisites](/getting-started/system-requirements) preinstalled. Then you can simply clone the repository: | ||
|
|
||
| ```render bash | ||
| git clone https://github.com/ProjectEvergreen/greenwood |
There was a problem hiding this comment.
We can anticipate that developers will be able to use npm/yarn to install Greenwood.
|
|
||
| Your project will generally have a structure like this: | ||
| ```render shell | ||
| ├── src |
There was a problem hiding this comment.
should we include an greenwood.config.js?
| You can compile your static site in development mode using: | ||
|
|
||
| ```render bash | ||
| yarn develop |
There was a problem hiding this comment.
Hmm, maybe we need to discuss final packaging, so we can make sure we have the right instructions. Might be worth chatting some more on the weekly call.
| "items": [] | ||
| }, | ||
| { | ||
| "index": 6, | ||
| "name": "Configuration", | ||
| "items": [] | ||
| "path": "/getting-started/configuration", |
There was a problem hiding this comment.
maybe configuration can come before development? If reading top -> bottom, configuration is mentioned in Development section. Just a though.
There was a problem hiding this comment.
A couple other thoughts I had for this (again understanding it is still WIP) were
Conveying the Narrative
Since we will have a dedicated section for all the technical stuff like page and app templates, configuration, etc in the Docs page, let's use this section to be as familiar and accessible with the reader as possible in regards to general Greenwood usage. The hope being that this page stays high level and focused on just one thing; helping a user install greenwood, author a couple pages, develop with it, build it, and host it.
We can always link to appropriate Docs section where possible, but ideally a user should be able to create a site without needing configuration per se.
As for that narrative, I guess a blog is probably a good use case to capture since it's certainly the target audience I think we're trying to capture. I think this goes hand in hand with....
Goals and Objectives
Adding clear goals will be helpful for keeping focus / scope on our end and setting expectations for the user / reader; a guided walkthrough that (hopefully) requires the least amount of Greenwood specific knowledge as possible.
Keeping with the blog example:
This guide will help you get started using Greenwood for your own blog using markdown. Through the course of this guide you will learn how to:
- Install Greenwood
- Developing with Greenwood
- Create a home page for your site
- Author some blog posts in markdown
- Style your site
- Hosting and deploying
By the end of this guide you will have a Greenwood project with some markdown based blog posts that you will be able develop with locally as well as build and host on any web server!
In essence the reader would go from nothing to something like this:
src/
pages/
index.md
blog/
<YYYY-MM-DD>
index.md
styles/
theme.css
template
page-template.js
blog-template.js
Anyway, just some additional thoughts to keep in mind.
There was a problem hiding this comment.
From our last meeting, our discussion around content yielded two action items related to this work:
- re-appropriate this content for the API Docs issue in a new PR (As a user I would like an (API) Documentation page for the project #20 ), by @hutchgrant
- Adopt a more narrative / guided experience for this particular content, by @thescientist13
The take away being that Getting Started should ideally provided a concrete flow and set of steps for first time user. Start from nothing, and end up with a basic site (blog?) with the minImum amount of Greenwood specific knowledge possible. (K.I.S.S.). The docs can be linked to appropriately to allow further investigation on a particular topic, but otherwise, Getting Started should be
- Welcoming
- Assume no / limited knowledge outside usage of npm , NodeJS, and simple command line
- Have a clear goal / outcome. The goal here shouldn't be to show off everything Greenwood can do, but instead how quickly you can get up and running without any prior knowledge and if anything, how little you even need to know of Greenwood. (e.g. create some folder, write some markdown, run a command, 💥 )
So will close this PR for now but the branch can / should definitely be used in both of these new approaches since the content here is valuable.
Related Issue
Resolves #98
Summary of Changes
This is a WIP.