1. Wikifying the documentation

Forked from Re: Help With Editing the Euphoria Documentation

euphoric said...

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.

euphoric said...

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

new topic     » topic index » view message » categorize

2. Re: Wikifying the documentation

ghaberek said...

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.

ghaberek said...

We need to maintain a single source of truth.

Yes. (And it needs gatekeepers.)

new topic     » goto parent     » topic index » view message » categorize

3. Re: Wikifying the documentation

euphoric said...

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

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu