metanorma / asciidoctor-rfc

AsciiRFC: an AsciiDoc/asciidoctor backend to produce RFC XML v3 (RFC 7991) and v2 (RFC 7749)
BSD 2-Clause "Simplified" License
15 stars 7 forks source link

docs: Add docs/ subtree for use with Ribose Open #106

Closed strogonoff closed 6 years ago

strogonoff commented 6 years ago

This is part of RO integration pilot. At this time please don’t mind the contents of docs/ and maintain only the README.

ronaldtse commented 6 years ago

Thanks @strogonoff , a technicality -- can we have Asciidoctor files rather than Markdown?

@opoudjis thoughts needed -- should these docs be kept in this gem, or a separate repo?

strogonoff commented 6 years ago

@ronaldtse I do think it’s important, AsciiDoc support is in fact is already among the objectives at https://github.com/orgs/riboseinc/projects/3.

At first approach I determined that AsciiDoc support in this theme (edit—or Jekyll in general) is not going to be plug-in-play. We can tackle this in upcoming milestones, or alternatively I can assist your team in adding adoc support to OP theme.

strogonoff commented 6 years ago

@ronaldtse @opoudjis It is a widespread practice to keep software docs in the same repository. I strongly recommend to follow this and keep the docs in the same repo as the codebase they serve although the theme may work with docs stored in a separate repo.

strogonoff commented 6 years ago

Expanding a bit on why docs belong with codebase:

opoudjis commented 6 years ago

@opoudjis thoughts needed -- should these docs be kept in this gem, or a separate repo?

I'm going to need a lot more context. What documents are you discussing? How-to and installation guides which will be ingested from this repository into a website?

As you know, the proliferation of gems and repositories in ribose is something I have never welcomed. I am sympathetic to @strogonoff's argument.

ronaldtse commented 6 years ago

Alright we'll keep them in the gem.

We plan to use docs/ in this gem to fill content for the https://www.asciirfc.com website (and https://www.metanorma.com). So this includes any Wiki pages we have, they should go to docs/ 👍

strogonoff commented 6 years ago

I'm going to need a lot more context. What documents are you discussing? How-to and installation guides which will be ingested from this repository into a website?

@opoudjis sorry for belated reply but yes.

@ronaldtse to give the this choice more credibility, docs subdirectory under repository root is also supported by GitHub as auto-detected location for the README file.

Have to agree with Nick in that fewer repositories is better in general. An extra repository for each package seems like unnecessary overhead.

We plan to use docs/ in this gem to fill content for the https://www.asciirfc.com website (and https://www.metanorma.com). So this includes any Wiki pages we have, they should go to docs/ 👍

Agreed that existing wiki contents will likely be migrated to docs. In future wiki can act as a sort of staging area for sharing information users find useful, before it makes it into proper docs.

I’m not sure if docs here will apply to both asciirfc.com and metanorma.com, because conceptually there’s one open project (Metanorma). Unless we define AsciiRFC as its own open project, and make it so that a given software package can be a member of multiple projects, the docs in this repo will only appear under metanorma.com.