Managing one source of the docs for both website and wiki #5
Description
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
- Migrate the Markdown format files (
_pages/*.mdand_posts/*.md?) on the website repositories [4] to this repository, converting it to AsciiDoc format. - 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