Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide spec summaries on Open Project sites (replacing full spec contents, where copied) #5

Open
strogonoff opened this issue May 21, 2018 · 0 comments
Assignees

Comments

@strogonoff
Copy link
Contributor

strogonoff commented May 21, 2018

Jekyll Open Hub theme does not advocate duplicating full specification texts into Open Project sites. This is not DRY, manually maintaining copies of content in sync is unnecessary friction.

(While it seems definitely not strictly necessary, if it is desirable for some reason to include a copy of content such as spec contents or software package docs into Open Project sites, a feature for Jekyll Open Hub theme, or build/CI configurations, should be requested to enable this sort of content to be pulled automatically from third-party sources such as IETF or RTD.)

However, design mock-ups at hand seem to offer the space for software/spec content. Jekyll Open Hub theme recommends to provide a description or useful summary in that case, which would include high-level information about the purpose, and exclude any changeable specifics such as installation instructions.

Some specs on currently implemented sites (RNP and Metanorma) include full contents instead of summary. That should be changed, options:

  • Include custom-crafted original spec description just for Ribose Open side (ideal option)
  • Copy IETF abstract, if available
  • Copy introduction part of spec’s GitHub README, if available

For the time being, going with the non-ideal options.

@strogonoff strogonoff self-assigned this May 21, 2018
@strogonoff strogonoff changed the title Provide spec summaries (replacing full spec contents, where copied) Provide spec summaries on Open Project sites (replacing full spec contents, where copied) May 21, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant