Build a wiki - Githubissues

spences10 / VBA-IDE-Code-Export

Export & Import VBA code for use with Git (or any VCS)

MIT License

119 stars 34 forks source link

Build a wiki #68

Closed spences10 closed 7 years ago

spences10 commented 7 years ago

So, we can use a wiki for when there's a bit more documentation than what should go in the README?

What do you think @mattpalermo

https://github.com/spences10/VBA-IDE-Code-Export/wiki

mattpalermo commented 7 years ago

I am mostly a stranger to the Github wiki. Github's documentation certainly makes it clear that the wiki is targeted at exactly the use case that you described. I'm all for giving it a go 👍 .

spences10 commented 7 years ago

Yeah, I have no experience with it either

I don't want to be repeating information that we have elsewhere as it could quickly become out of date if the releases/readme get updated without the wiki and vice versa

Maybe just point to the wiki for anything that can not be explained in a couple of paragraphs

mattpalermo commented 7 years ago

We could keep on top of it by issuing github issues (and asking users to do the same) if any documentation was found to be out of date or incorrect.

spences10 commented 7 years ago

Just looking at the source and this could be a good candidate for the release instructions #41

Also, possibly add instructions for building from source, currently it is all in the README

off to Google!! what-are-the-main-functionality-differences-between-github-wiki-and-readme

Ok, maybe we're making way more work than we need to here

README: should be a summary of the project

Wiki: is for contributors documentation

When someone clones the repo, do they really want the gifs that go with the README?

Fuck it! For now I'm just going to concentrate on getting the tool doing what it's meant to do, the README can still serve as an attention grabbing device with the gifs in there

IMO the README should quickly convey what the repo does to the user without them getting confused and moving on

Don't want to make an industry out of it but will document what needs documenting

mattpalermo commented 7 years ago

@spences10 I don't think it's something to worry about too much. What we have so far is good. Here is my thoughts:

It is good to have documentation source code (e.g. md files and their assets) in the repo. Consider the benefit of documentation VCS. If the documentation requires rendering, then the rendered version should be available somewhere. For markdown files, the rendered HTML version is available via GitHub. Alternatively or additionally, the documentation could be published on a website.
Only move away from this for a good reason. Here are two reasons why documentation might be moved to a Wiki:
- Community engagement. The theory is that end users will be more comfortable contributing to documentation if they can just use a web interface.
- Content management. The Wiki can take care of automating a few things that have to be done manually if the documentation is written in plain text files.

spences10 commented 7 years ago

Closing this