Consolidate documentation

[bclothier]

Right now, we apparently have 3 places for documentation:

On the wordpress site On the rubberduck site On the wiki

The real problem isn't that there's 3 places for it, but rather that they are all each a bit different and thus are not always up to the date. For example, some screenshots are outdated, some are completely missing some feature. For example, the wiki and RD site has nothing on Settings. The WP site has the most up to date description on Settings.

We need to consider whether we want to keep all 3 sites, and if we do elect that, look into ways to make it easy for us to distribute changes in the documentation to each endpoint.

[PeterMTaylor]

A central place for documentation with a way to generate current snapshots is a good way to go automated or not. 👍

[mansellan]

TBH I didn't even know that the WP site had docs, I thought it was just the blog.

Agree that we should consolidate, even to go as far as to say that WP should disappear... IMO there should be an authoritative RD site (rubberduckvba.com) which should host an intro, news, the blog, user instructions, a quick and direct link to the latest green release (not a link to GH, go find it yourself), and links to the GH repo and wiki (for technical and contribution docs).

Ideally, with well-known and reliable doc URLs, we could start to embed Help links into RD menus,

Just my 2c (and I know replacing WP with an in-site CMS is non-trivial).

[bclothier]

AIUI (and @retailcoder can correct me), the RD site isn't exactly the easiest thing to manage, which is why WP site has gotten more updates. RD site isn't a LAMP which kind of hinders the idea of installing Wordpress on it. (It can be on Windows but do you really want to run Wordpress on Windows?!? Huh uh. Didn't think so...)

One thing bears calling out is that the GH's wiki can be used like a 2nd repo and thus can be used via the git workflow. Some one solved the problem of transferring the xmldocs to the wiki here: https://github.com/neuecc/MarkdownGenerator

So in theory, we can make it easy to update wiki by consistently asking contributor to update/maintain the xmldocs. That helps the contributors. For user-facing documentation, we can look at using wiki as a git repository to maintain the documentation.

[mansellan]

Love the idea of using xml docs to drive site MD (duck check: is this SandCastle for 2018?). But how does this solve for blogging?

[PeterMTaylor]

I guess on this thread of blog thought/conversation we could consider blogging containing modular behaviour in yaml Jekyll behaviour works with yaml files put together (built as depend after successfully done XML-doc) by sections of generated HTML of content interest. For examples/ideas... https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/ I have followed someone’s setup to make my test webpage ending with *.GitHub.io I’m considering blogging soon.

[mansellan]

Um, yeah, Thanks for that, Anything else?

[Vogel612]

Something we could toss around is the idea of using GH-Pages to segregate external documentation from internal documentation. That way the internals can be documented in the wiki and the user docs can go to rubberduck-vba.github.io/docs

[bclothier]

But how does this solve for blogging?

It doesn't - as mentioned it's mainly useful for internal developer's documentation. User documentation likely needs to be maintained separately anyway since the categorization will be quite different when looking at the ducky as a user vs. as a developer.

If we can have both user documentation and blogging maintained by same software, that would be a win in the maintainability. Whether there's a software that supports all features typically needed in a blogging and in a user documentation.... :\

[Vogel612]

Another article linked by Peter explains how we can update the wiki from an AV build, so long as we do it right: https://www.growingwiththeweb.com/2016/07/enabling-pull-requests-on-github-wikis.html