search

publiclab / plots2

a collaborative knowledge-exchange platform in Rails; we welcome first-time contributors! :balloon:
https://publiclab.org
GNU General Public License v3.0
958 stars 1.83k forks source link

Wiki vs .md files in repo #5848

Open sashadev-sky opened 5 years ago

sashadev-sky commented 5 years ago

I wanted to bring to attention issue #4337 and ask why we moved all of our documentation out of Wikis and into .md files at some point?

I really like the Wiki interface! It makes documentation a lot easier to follow because you're not reading in .md syntax. And also easier to organize and remind people what's available because the topics are shown right there (instead of in a folder squished between all the other folders in a rails project)

sashadev-sky commented 5 years ago

Tagging some people that might be interested in this discussion @SidharthBansal @skilfullycurled @gauravano @jywarren

grvsachdeva commented 5 years ago

Hmm, one explanation which comes to my mind is the fact that having documentation in the folder structure makes it more visible, whereas wiki option is kind of hidden at the top. Most new contributors try to understand the codebase by directly going through the readme so need to put links to wiki there. But, the same goes for documentation.

Actually, we can discuss here what things are more suitable as wiki and what makes sense as docs? What do you all think?

sashadev-sky commented 5 years ago

@gauravano I was thinking the more we move out of the Rails app the better because there are so many files at this point

jywarren commented 5 years ago

@icarito has mentioned this because docs in the repo means you have them offline, and also because I've found that wiki docs are disconnected enough that we often miss when they are made. But I don't have a strong opinion except that I generally don't wish for docs to be split up. Thanks!!

On Wed, Jun 5, 2019, 10:56 PM Sasha Boginsky notifications@github.com wrote:

@gauravano https://github.com/gauravano I was thinking the more we move out of the Rails app the better because there are so many files at this point

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/plots2/issues/5848?email_source=notifications&email_token=AAAF6J6CIS6FA25HXLPGLSTPZCRFLA5CNFSM4HUSX7E2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXBZZ5A#issuecomment-499358964, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAF6JYBWL42DOPUDYJ6EB3PZCRFLANCNFSM4HUSX7EQ .

skilfullycurled commented 5 years ago

Thanks for inviting me @sashadev-sky. Actually, when I first started out I found the fact that the documentation was located in the codebase confusing. This was/is exacerbated by the fact that the github home page does not have a link to the documentation except for a specific link to the documentation for the email. I just did a search for "doc" but maybe it has a different name?

I agree with @sashadev-sky. To me, the benefit of the wiki is that you can see all of the documentation in the sidebar. I might be reading about something which mentions "code climate" and think "what's that?" but save having a great memory, I have no indication that this is something I can learn more about. The benefit of the wiki is that I can quickly learn about code climate, and then go back to what I was reading. Having the docs in a folder means I am twice removed from the place I left off.

There are a few conventions that come to mind regarding documentation:

1) High level documentation (which I think ours falls under) is usually in the wiki (if not in the docs, see item 2). I agree with @gauravano that this is harder to find, but people familiar with github may look here first, and for those unfamiliar, both locations will be unexpected.

2) There is a "docs" folder from which lower level documentation is generated (e.g. Sphinx). To me, a docs folder isn't to be looked at because it only serves to provide me with a human readable version some place else.

3) Many people have a link to their documentation at the top. Admittedly, this is often because they are libraries so you're being redirected back to the home page of the library where the documentation is, but often it's the link to the actual documentation.

The benefit @icarito points out is important especially if you're in a place where internet access is spotty. I don't live in an area with spotty internet access, but personally, I could have the documentation for every language and library past, present, and future, and without a search engine I'd be paralyzed. So while I don't see the the offline aspect outweighing the benefits of the wiki version, it's worth reemphasizing that since I haven't lived this experience I haven't been forced to learn to overcome that paralysis. I suppose there's no reason why we can't have both except that might require having to update everything twice?

We spoke a short while ago about having @ebarry's survey as part of the follow up bot to first timers. Maybe a question should be added such as "Were you able to find the documentation?" and if so "Did you find it useful/what would make it more useful?"

sashadev-sky commented 5 years ago

Hmm well for a start, I was thinking we should remove GCI_MENTOR_GUIDELINES.md into a wiki on the actual PL site. And perhaps link it as a resource ini https://github.com/publiclab/plots2/wiki/Open-Source-Programs

This cleans and doesn't involved splitting the folder. It just seems like Open Source Programs have a home in the wikis now.

What do you think? @jywarren

jywarren commented 5 years ago

Sasha, that sounds fine to me.

Just some questions that may help us decide here:

  1. do people feel either the wiki or the /doc/ folder is more "permanent" in some way? Easier to edit?
  2. is either one easier to see who wrote the docs? as this is sometimes helpful to know when you want to ask questions

Thanks!

On Fri, Jun 14, 2019 at 4:14 PM Sasha Boginsky notifications@github.com wrote:

Hmm well for a start, I was thinking we should remove GCI_MENTOR_GUIDELINES.md into a wiki on the actual PL site. And perhaps link it as a resource ini https://github.com/publiclab/plots2/wiki/Open-Source-Programs

This cleans and doesn't involved splitting the folder. It just seems like Open Source Programs have a home in the wikis now.

What do you think? @jywarren https://github.com/jywarren

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/plots2/issues/5848?email_source=notifications&email_token=AAAF6JZKLR5YKYJIVHTYUHTP2P3ZZA5CNFSM4HUSX7E2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXX3GOI#issuecomment-502248249, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAF6J5LQ5GM6MMTXR63K5DP2P3ZZANCNFSM4HUSX7EQ .

skilfullycurled commented 5 years ago

@jywarren, I can't tell if you are connecting "permanence" in relationship to hard/easy to edit or if you mean "can be kept for all time". I'm not sure why the wiki or /docs/ folder wouldn't each be of the same permanence in the latter sense but here are the similarities/differences as described in the github documentation.

Both the wiki and the /docs/: 1) can be edited in the browser or locally 2) are subject to the commit, approval, and merges process 3) can be written in markdown or other similar mark-up languages 4) can be downloaded for offline access (since they are converted to markdown either way)

However: only the wiki can be edited using a rich-text-like editor.

The solution @sashadev-sky proposed for the GCI_MENTOR_GUIDELINES.md file could be the basis for a temporary compromise between the two.

For the time being we could:

1) Keep the location of the docs as they are 2) In the wiki, make a list of all of those docs with links to them but: 2a) Give each file a more descriptive name 2b) Provide descriptions of what information each file contains

Pros:

Continuing Cons:

jywarren commented 5 years ago

Great list of pros/cons. Here's another thought to add to the mix:

Not essential, just nice!

skilfullycurled commented 5 years ago

@jywarren, can you explain a bit more? How would that differ from the fact that the wiki also requires commits and is therefore (I assume) version tracked. Just clarifying, in the end I don't have a team in the game. Or, at least not one I'm partial to.

I'll also add that one way to look at it (via a TED talk I saw, will try to locate) is that some pro/con lists aren't helpful because both options are "on par'. In which case, in looking at the different affordances, we can ask, "what are we for". The example in the talk is that the speaker wasn't sure about being a lawyer or philosopher and both choices were "on par" for her. In the end, she decided she was not "for lawyer-ing".

grvsachdeva commented 5 years ago

Some cases where wiki might help:

In the wiki, make a list of all of those docs with links to them but: 2a) Give each file a more descriptive name 2b) Provide descriptions of what information each file contains

Agree! And, want to add, maybe we can drop some more info too with the links?

jywarren commented 5 years ago

@jywarren, can you explain a bit more? How would that differ from the fact that the wiki also requires commits and is therefore (I assume) version tracked.

Ah, just that when you have code (and docs) in the same PR (esp. the same commit) as features, you can often use that link to trace who wrote code, follow it back to the docs, and figure out how and why it works.

Example: this code for reply-by-tweet is not running yet:

https://github.com/publiclab/plots2/blob/ba6f3b8a25ac4f6aeaaa2d9fab8e4d57778c83c3/app/models/comment.rb#L356-L361

So you can click on the commit (ba6f3b8) and it leads you to the docs:

https://github.com/publiclab/plots2/commit/ba6f3b8a25ac4f6aeaaa2d9fab8e4d57778c83c3#diff-b4ffc55dae199a30216ef1a14ee564e2