Feature Request: Implement Github Wiki for Odin Pantry

[taladan]

Feature: Wiki Knowledgebase

Why?

A well documented project is a project that people can contribute to.

Finding out information about a project when documentation is held in disparate places makes it less efficient and more cumbersome to navigate. Things like MDN, Ruby-doc, etc. are well known, well used and well loved (and sometimes hated...yes, sometimes) resources for all of us.

When I suggested the idea in DC, Biff asked me about what I see for something like a wiki, and my answer was: I don't have a specific vision for it. So, in that vein, I'm doing some research and throwing some ideas to the wall. I would prefer that this get a good bit of discussion before any kind of implementation is done, and I'm not volunteering to run it at this point either - not that I wouldn't love to, but I don't have the time nor the specific knowledge of the more advanced programmers to be able to produce the documentation.

I know that everyone has different feelings about documenting code - some of us are sparse documenters, letting the code speak for itself and only putting in documents when some sort of clarification seems necessary. Others of us document freely with plenty of context and description. This sort of documentation is expected and (usually) accepted by our peers.

Alternatively, the sort of documentation an open source project requires is meant for a different audience. Eventually successful open source projects attract people of many varied skills, from artists, writers, tech-literate users looking for answers, and even, yes, a few developers. Look around at most highly successful open source projects, you'll see branding, marketing via organic social media interactions, volunteers giving time and effort to moderate subreddits, logos and swag designed, sold, ripped off, copied, and spun. These sorts of projects usually have a navigable, searchable database of documentation that explains what the project is, what it does, how it does it, why it does it, how people can use it, access it, implement it, and contribute to it.

Well written documentation may not be the backbone of a good opensource project, but I would say it's at least worth a leg or two.

Who?

Although I believe that the wiki will end up being managed by one or two people to clean up/enforce formatting stuff on PRs to add to the wiki (assuming that's how github does it), and do the general maintenance task of handling tagging and organizational issues, the documentation is ultimately up to us. If you write a widget and send it up for a PR and it gets implemented, if you're not submitting some sort of external documentation that at least gives a few words about what the thing is and does and why it exists, then you're shuffling half the job and a good bit of heavy lifting for the next person to come along, decipher your code and document it in an understandable and consistent format.

We don't have a budget to hire tech writers, so we /are/ the tech writers. Scary, I know.

How?

As stated previously, consistency will be key here. Whether we want to maintain seperate pull requests for the wiki or automate the process of pulling info from the /docs folder and automagically linking and formatting it within the searchable wiki, what will matter most to someone reading the documentation will likely be things like:

• clarity of purpose
• ease of locating information
• consistency in formatting
• understandable language

These are all things that increase the usability of a well documented project. That said, we would need to agree on formatting of documentation and the specifics of where the docs are to be submitted. That raises questions about things like:

• Are patchnotes seperate from the documentation?
• at what point should there be seperate developer documentation vs. user documentation?
• If we decide to go with automation what does that even look like?

When?

I would suggest that when a PR is submitted that does the following:

• Implements or changes a major feature or versioning change or breaking feature
• Implements or changes a minor feature or versioning change or breaking feature
• Affects functionality or interface
  Documentation should be included in whatever format or template with whatever appropriate tags pre-required by the community for automation purposes before the PR is accepted for implementation into the project.

Finishing up

I think that this topic deserves a good bit of discussion. I will list below some examples that are apparently considered 'good' examples of opensource project documentation wikis:

• Titan

• Hystrix
• D3

I'm sure most of you have come across documentation that you appreciated at one time or another, so feel free to pitch in and toss some input into the conversation, links, suggestions, arguments for or against.

[JustWaveThings]

The example wikis seem directed at the users of the app, not the developers. I see value in the wiki for projects of their size (D3, Titan, Hystrix), but maybe not so much value for the pantry app, not at least until we get ready to release something into the wild. At that time, I think there'd be a benefit to then taking on the wiki and maintaining it.

This is just my inexperienced opinion and i'll be happy with whatever the group decides regarding this matter.

[Philip-Clark]

Converting this to a discussion.