Closed strogonoff closed 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?
@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.
@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.
Expanding a bit on why docs belong with codebase:
As with tests, it is arguably good discipline to update documentation as you make changes to relevant parts of the code. With conventional GitHub flow, spreading these across repositories results in unnecessary headache for project maintainers or out of sync stale docs.
Documentation versioning is important. Although that feature is not there yet, the documentation system that is part of Open Project theme was envisioned with the ability to build documentation for multiple versions based on tags in software or spec repository. (To achieve that with a separate docs repo means to take care of adding version tags in that repo as well, more mechanical work that your staff or maintainers would probably hate to do.)
@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.
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/
👍
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.
This is part of RO integration pilot. At this time please don’t mind the contents of docs/ and maintain only the README.