Contributors Setup Guide

[BolajiAyodeji]

I'm not sure if one exists before now, but no guide shows how to set up this project for new contributors. I guess this should be in README.md or CONTRIBUTING.md that explains how to install Jekyll and get this project running on a local machine.

Also, looks like the Contributors guide used here is more for documentation in general with less relation to the context of contributing to this repository. So contributors viewing the repository from GitHub might get a different view and we might need another contributor guide here?

@camerons is there any reason why this doesn't exist?

If there isn't any, I can spin up a README for this.

[ScriptAutomate]

Yeah, too much is missing. Needs:

How the Repository Functions

• Uses GitHub Pages?
• Does it use master branch, since other branches haven't been updated in a long while, or?
• What's the contributing method? Should it be the standard fork -> branch -> PR to master?

Prerequisites

What are the prereqs for this project when contributing? What's needed for development?

• Ruby (version minimum?)
• Jekyll (and if version minimum?)
• Bundler (and if version minimum?)

Anything more than this?

Local Development Environment

What about steps to build the site, before starting to make changes? How to view locally?

With bundle now available (after prereqs met), I've tried the following but it doesn't work properly (I am working on a fresh branch split from master):

bundle config set --local path 'vendor/bundle'  # Local ruby/gems/bundle env
bundle install # Install everything in Gemfile.lock
bundle exec jekyll serve # Run local Jekyll server for visual dev/confirmation

Errors arise. First, jekyll-theme-slate is being used in _config.yml, but is not referenced in any file outside of _config.yml. How is this being managed?

So I did:

bundle add jekyll-theme-slate

That installed the dependency and modified the Gemfile.lock to include it. Why was it missing? Am I using the wrong branch config? It now serves, but the theme isn't properly working, and I also get a ton of warnings in output when doing bundle exec jekyll serve.

I ignored the warnings, tried to view the site, but no theme is catching. It just presents as a file/dir tree.

So, I decided to go with the latest and greatest and see if any difference occurs:

mv Gemfile.lock Gemfile.lock.bkup
rm -rf vendor
bundle install
bundle exec jekyll serve

No more of the verbose warning output, but site still doesn't function for development viewing. The way to develop, contribute, locally preview, etc. all needs to be documented in this repository, along with how/where it is published online and if there is a multi-step approval process for deploying live.

[emckean]

Another question: before we go too far down the road w/Jekyll, we have also talked about doing a Docsy (Hugo) site. (Docsy is a docs-focused theme for Hugo).

I'm happy to do a quick port of this content to Docsy and then we can do a bakeoff? :)

[ScriptAutomate]

I'd be onboard with Hugo/Docsy. The tooling would be easier to work with, and it can be documented from there? :)

[Loquacity]

As I was doing some planning for the Base Template (previously "Template of templates") I realised that it should probably serve the function of a contributors' guide. See https://docs.google.com/document/d/1Ym1J031pkYZC6_XBQCRl4TmX98S9O3xu2I7zQjRK6o8/edit?usp=sharing

[mgan59]

Yeah same issue here -- just a directory/folder listing.

[mgan59]

oh I got it to work, the frontmatter is missing on the index.md

[mgan59]

For verification add the following:

---
title: My page
layout: default
---

to index.md so it should look like

---
title: My page
layout: default
---

_“Best practice templates and writing instructions for documenting open source software.”_

### Download

* The [0.1 alpha straw-man release of templates](https://github.com/thegooddocsproject/templates/releases/tag/v0.1) was released at the 2019 Write The Docs - Australia conference.
* The latest development version of templates are available from the [github master branch](https://github.com/thegooddocsproject/templates).

### Why?

Every project deserves a minimum level of _Good Docs_ that help users understand and solve problems with your product. But it can be really hard to know where to start or what to write. How do you structure docs? What does a docs website look like? How do I keep docs consistently formatted? The list of questions far outweigh the answers.

That’s where _The Good Docs Project_ fits in. Our open-source Minimum Viable Docset (MVD) will help you create a baseline set of _Good Docs_ using a suite of templates.

Your _Good Docs_ can then be extended into _Better Docs_ with greater depth, quality and maturity.

Providing writing templates:

* Amplifies the writing effectiveness of developers, power users writers, and more.
* Improves doc quality and consistency across the board.
* Facilitates the democratization of knowledge.
* Leads to self-empowerment and the betterment of humankind.

And the bundle exec jekyll serve will work. We can update the title attribute. Now the question is how is this thing deployed for it to be working?

[emckean]

here's a link to a quick Docsy version of the current site (I only really updated the first page to show the branding and a few links) https://practical-bell-d6e0a2.netlify.app/

[bwklein]

There is a ReadMe at the root of the new website project for this purpose. It could be extended to provide instructions for different OS dev environments, but I would recommend adding a feature request to that project, or creating a PR with any details that should be added.