Documentation - help wanted!

Excellent!

Consider Asciidoc for the format, which would allow for a standard method of inter-document linking and other features, plus easy conversion to other formats. (GitHub previews Asciidoc as formatted HTML in PRs etc. just like it does Markdown.)

Beyond setup, the first editorial job is to compile a list of known target topics:

  • high level concepts people don’t quite grok, such as how the various gems relate to each other or the relevant Ruby basics, etc.,
  • frequently asked questions or frequently answered answers,
  • use cases that can be discussed in focused documents,
  • other subject areas that would make sense as guides or part of a guide.

Triaging this could be as simple as applying a “guides” tag to GitHub issues and/or forum discussions that seem like relevant guide fodder.

1 Like