1. Wikifying the documentation
- Posted by ghaberek (admin) Sep 20, 2019
- 1188 views
Forked from Re: Help With Editing the Euphoria Documentation
Once the new 4.1 docs are online, how do we wikify it?
The source content for the docs (in comments or in text files) are already in Creole format, so they're already (mostly) wiki-ready. There may be some massaging needed to make it fit but not much.
And, again, how do we integrate future changes to the source in that online docs wiki?
In order to use the wiki for documentation, we need to move the source content from its current home to the wiki. We need to maintain a single source of truth. All of the content in docs/ should just be removed and the comments in all of the std/*.e files should be slimmed down to be comments, not documentation.
I think it's great that anyone will be able to edit the documentation, but I'm also worried that anyone could edit the documentation, so perhaps some gate-keeping may be required. We should probably implement namespaces in the wiki so we can separate "manual" pages and other "content" pages and allow for more fine-grained permissions via additional roles.
I also thing we should clean up the wiki in preparation to receive the docs. Unfortunately it suffers from the same state as the docs. There's a lot of duplicate and outdated content that needs to be reviewed and updated or discarded.
-Greg
2. Re: Wikifying the documentation
- Posted by euphoric (admin) Sep 20, 2019
- 1187 views
In order to use the wiki for documentation, we need to move the source content from its current home to the wiki.
It seems what needs to happen is we release 4.1.0 with the same system we have now, including uploading the new docs from source.
THEN, we will have a set of HTML docs we can transition to a wiki-style (?) (or keep as creole), as well as pull the docs from the source.
We need to maintain a single source of truth.
Yes. (And it needs gatekeepers.)
3. Re: Wikifying the documentation
- Posted by ghaberek (admin) Sep 20, 2019
- 1131 views
THEN, we will have a set of HTML docs we can transition to a wiki-style (?) (or keep as creole), as well as pull the docs from the source.
The way the wiki works right now, is that it stores the Creole markup and a the HTML output. When you view a page, it sends you the HTML.
When you edit a page, it sends you the Creole markup. When you save changes, it runs the Creole markup through the parser and then stores both versions as a new row, indicating an "edit" to the page.
-Greg
