Managing one source of the docs for both website and wiki

[junaruga]

Summary

We standardize on writing documents in AsciiDoc format [1], managing the document source to be used for both the website and documents that are currently managed on each repository's wiki [2] in one place, here "CHRIS_docs" repository.

Background

According to the analysis FNNDSC/ChRIS_contributor-support#6 (comment) for the current situation, improving the people's process to start the project is important. When we see the page [3] at chrisproject.org to run the ChRIS UI that can be people's starting process, we see the website page's content is older than the wiki page's one. We think the good documents enable people to come and stay with this project, and enable us to create the small tasks for first contributors.

Steps

1. Migrate the Markdown format files (_pages/*.md and _posts/*.md?) on the website repositories [4] to this repository, converting it to AsciiDoc format.
2. Migrate the Markdown format files on each repository's wiki to this repository, converting it to AsciiDoc format, merging it.

Notes

Right now we go for managing AsciiDoc format rather than Markdown format, because

• We know a lot of projects are moving from markdown to asciidoc.
• The Markdown format does not have a single clear specification.

Here is the detail from @mairin on Slack.

@Jun Aruga no like i said on the call im not sure why its so popular nowadays, i know a lot of projects are moving from markdown to asciidoc. i suspect it's because the templates available for rendering are nicer in asciidoc but im not sure, and its not my expertise
@Jun Aruga certainly if we were to attract a docs-savvy contributor and they decided asciidoc wasnt the way to go we'd defer to their expertise
i do have some experience trying to render markdown out nicely and its kind of pain, especially since markdown doesnt have a single clear specification, there are too many flavors of it

References

• [1] https://en.wikipedia.org/wiki/AsciiDoc
• [2] Ex. https://github.com/FNNDSC/ChRIS_ultron_backEnd/wiki
• [3] https://chrisproject.org/join-us/get-chris-running
• [4] https://github.com/FNNDSC/website

[junaruga]

As I see @mairin and @jennydaman working with ascii doc on this ticket, I changed the status to "In progress".

https://fnndsc.slack.com/archives/C04FLFUA6/p1605200327212000

duffy 5:58 PM I have been playing around with ASCIIDOC this week and I talked to a resident expert at Red Hat, so far I have it outputting eminently clean & styleable HTML, and it also generates github-friendly md. So i think it could work for us