From aa104bec0f5747615c8ce4ca59578ececf7dcc08 Mon Sep 17 00:00:00 2001 From: Mat Dave Jones Date: Thu, 13 Apr 2017 09:41:59 -0500 Subject: [PATCH 1/2] Create markdown-rtfm.md --- markdown-rtfm.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 markdown-rtfm.md diff --git a/markdown-rtfm.md b/markdown-rtfm.md new file mode 100644 index 0000000..4df6d41 --- /dev/null +++ b/markdown-rtfm.md @@ -0,0 +1,22 @@ +Convert the RTFM (Docs) to MarkDown +################ + +I propose changing the documentation to a markdown system and hosting the repository on github. + +* **Editor:** Matthew (matdave) Jones +* **First published draft:** 2017-04-13 +* **Accepted:** Not yet voted. + +## Goal of Recommendation + +The current docs have only a few editors, and are constantly falling out of date. Converting to a MarkDown system would allow more community members to keep them up-to-date. + +## Relevant Recommendations + +No relevant recommendations. + +## Recommendation + +Currently the RTFM is a pain to manage, and is falling out of date. It is also hard, as an editor, to know when a page was last updated until you are actually on that page. + +I propose converting the documenation system to Daux.io, or something similar, to make it easier for third party developers to integrate documenation, as well as allowing the community to take part in furthering the documentation. Additionally, it would allow people to see change history of a specific document if they are on a different version. From 5a78134f8e8783a53549d56aaa4f2cb9e082c46c Mon Sep 17 00:00:00 2001 From: Mark Hamstra Date: Thu, 29 Jun 2017 13:18:10 +0200 Subject: [PATCH 2/2] Rewrite draft to better explain reasoning and benefits of markdown/github --- markdown-rtfm.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/markdown-rtfm.md b/markdown-rtfm.md index 4df6d41..40551be 100644 --- a/markdown-rtfm.md +++ b/markdown-rtfm.md @@ -1,7 +1,7 @@ -Convert the RTFM (Docs) to MarkDown +Convert the Documentation to Markdown ################ -I propose changing the documentation to a markdown system and hosting the repository on github. +To increase community involvement and to make it easier to manage, the official documentation should be changed to markdown-based structure, backed by a public GitHub repository. * **Editor:** Matthew (matdave) Jones * **First published draft:** 2017-04-13 @@ -9,7 +9,7 @@ I propose changing the documentation to a markdown system and hosting the reposi ## Goal of Recommendation -The current docs have only a few editors, and are constantly falling out of date. Converting to a MarkDown system would allow more community members to keep them up-to-date. +To make the [official MODX documentation](https://docs.modx.com/) easier to manage. ## Relevant Recommendations @@ -17,6 +17,17 @@ No relevant recommendations. ## Recommendation -Currently the RTFM is a pain to manage, and is falling out of date. It is also hard, as an editor, to know when a page was last updated until you are actually on that page. +Currently to edit the MODX Documentation, a separate user account that can only be used for the documentation is necessary to make changes. This results in a limited number of editors keeping the documentation up to date. There is no approval workflow: anyone with access can remove or make changes, without any verification or process to ensure the changes are correct. There's also no (publicly visible) history. -I propose converting the documenation system to Daux.io, or something similar, to make it easier for third party developers to integrate documenation, as well as allowing the community to take part in furthering the documentation. Additionally, it would allow people to see change history of a specific document if they are on a different version. +To improve the documentation, it should be moved to a Markdown format, hosted on a public GitHub repository. Daux.io, or a similar tool, could be used to build and serve the documentation. + +Using Markdown in a public GitHub repository achieves the following: + +- Editors do not require a separate user account only for the documentation. A GitHub account is needed, which does not appear to be prohibitive based on activity on the [documentation issues repository](https://github.com/modxcms/Docs/issues) or the primary [Revolution repository](https://github.com/modxcms/revolution). +- Puts in place an approval workflow through pull requests. This allows anyone to propose changes, including directly from the GitHub interface. Anyone can comment on pull requests for review, while a limited group of trusted individuals would be given access to merge and push changes. +- Git keeps a full, detailed history of changes, which is browsable on GitHub. +- Markdown is a flat-file format that is easy to process into other formats. This would allow future enhancements to the way content is displayed or distributed. + +Combined, these improvements are expected to result in more community activity in keeping the documentation up-to-date and to improve it over time. + +As moving the documentation into a markdown format is a big project, a Working Group should be formed to coordinate the effort. \ No newline at end of file