search

RobotGarden / RobotsForKids

This is our collection of educational materials on robotics for children.
Apache License 2.0
1 stars 5 forks source link

Wiki vs. Markdown Files #5

Closed j12y closed 8 years ago

j12y commented 8 years ago

Hi @merose and @javatechs

Would either of you have any objection to me moving the list of items from the wiki into a repos markdown file? I think for editing / preview it would be on par with the wiki but would also have all the added features of being able to merge contributions from many, move things around, collaborate with issues and commits, reviews, etc. that aren't core features of github's wiki. I just wanted to check first if there were some benefits to using the wiki I might not be thinking of.

See these examples for what I was imagining could be a valuable outcome of our research and planning for an open learning / makerspace curriculum and activities:

merose commented 8 years ago

Hi Jason,

The Wiki on Github already uses Markdown syntax, and it's already a repository, so I think it's already set up the way you want. Each Github repository has an associated Wiki repository which you can clone using the URL shown on the Wiki home page on the lower right

The two repositories are designed, I think, such that the Wiki is good for docs you don't intend to release with the code, but since they are both Github repositories, there's not much difference. In that regard I have no objections to restructuring everything under the code repository, but you lose some Wiki features.

Reasons to use the Wiki:

Reasons not to use the Wiki:

You guys can decide.

(Also, does RobotGarden have a Google Docs for nonprofits account? Some docs like parts lists are much more convenient in a spreadsheet, and I'd rather avoid the Office vs. Open Office conflicts.)

Mark

Mark Rose markrose@acm.org 925.922.7263

On Oct 17, 2015, at 11:15 PM, Jayson DeLancey notifications@github.com wrote:

Hi @merose and @javatechs

Would either of you have any objection to me moving the list of items from the wiki into a repos markdown file? I think for editing / preview it would be on par with the wiki but would also have all the added features of being able to merge contributions from many, move things around, collaborate with issues and commits, reviews, etc. that aren't core features of github's wiki. I just wanted to check first if there were some benefits to using the wiki I might not be thinking of.

See these examples for what I was imagining could be a valuable outcome of our research and planning for an open learning / makerspace curriculum and activities:

vhf/free-programming-books ashleymcnamara/STEM_Resources_For_Kids — Reply to this email directly or view it on GitHub.

javatechs commented 8 years ago

I'm good - either works for me. I appreciate you making it a discussion.

On Sun, Oct 18, 2015 at 8:30 AM, Mark Rose notifications@github.com wrote:

Hi Jason,

The Wiki on Github already uses Markdown syntax, and it's already a repository, so I think it's already set up the way you want. Each Github repository has an associated Wiki repository which you can clone using the URL shown on the Wiki home page on the lower right

The two repositories are designed, I think, such that the Wiki is good for docs you don't intend to release with the code, but since they are both Github repositories, there's not much difference. In that regard I have no objections to restructuring everything under the code repository, but you lose some Wiki features.

Reasons to use the Wiki:

  • better on-line editing and preview (auto-creation of new pages, e.g.)
  • built-in navigation bar
  • good for docs that aren't code-related (e.g., one of my repos is an Arduino library for a robot; the Wiki has parts list and assembly docs, the code repo has docs on using the library)
  • people used to Wiki documentation will click the Wiki menu item expecting further docs.

Reasons not to use the Wiki:

  • one less repository to deal with
  • all docs are related to the code (for code-oriented repos)
  • people might not notice the Wiki
  • preference

You guys can decide.

(Also, does RobotGarden have a Google Docs for nonprofits account? Some docs like parts lists are much more convenient in a spreadsheet, and I'd rather avoid the Office vs. Open Office conflicts.)

Mark

Mark Rose markrose@acm.org 925.922.7263

On Oct 17, 2015, at 11:15 PM, Jayson DeLancey notifications@github.com wrote:

Hi @merose and @javatechs

Would either of you have any objection to me moving the list of items from the wiki into a repos markdown file? I think for editing / preview it would be on par with the wiki but would also have all the added features of being able to merge contributions from many, move things around, collaborate with issues and commits, reviews, etc. that aren't core features of github's wiki. I just wanted to check first if there were some benefits to using the wiki I might not be thinking of.

See these examples for what I was imagining could be a valuable outcome of our research and planning for an open learning / makerspace curriculum and activities:

vhf/free-programming-books ashleymcnamara/STEM_Resources_For_Kids — Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHub https://github.com/ProgrammingRobotsStudyGroup/RobotsForKids/issues/5#issuecomment-149025047 .

j12y commented 8 years ago

:+1: for google docs/spreadsheets as they are super helpful for collaboration

Nice, I didn't realize you could clone the wiki repos itself, that's at least helpful for most of what I was concerned about with editing / publishing workflow. I'm probably in the category of people who never looks at the github repos wiki though since many of projects I've seen at least didn't use it.

Either way, I am highly in favor of keeping everything together so that it doesn't require going back and forth between the two. We could also revisit as we get a better sense of what we start to aggregate in the repos and how to organize the information and resources. I suppose I wasn't imagining much in the way of code so if we use the wiki there isn't anything to put in the repos itself yet.

pryme commented 8 years ago

I'd add my strong support for google docs / spreadsheets. If iGate / RG is eligible for a Google account for non-profits, this could be nice path to better collaboration tools (and it's free).

javatechs commented 8 years ago

I invited Patrick, Jayson, J and myself to PRSG's drive. I already had the account, so adding gdox was simple.

On Mon, Oct 19, 2015 at 7:49 AM, Patrick notifications@github.com wrote:

I'd add my strong support for google docs / spreadsheets. If iGate / RG is eligible for a Google account for non-profits, this could be nice path to better collaboration tools (and it's free).

— Reply to this email directly or view it on GitHub https://github.com/ProgrammingRobotsStudyGroup/RobotsForKids/issues/5#issuecomment-149237721 .

merose commented 8 years ago

Hi Fred, Can you invite me, too? mark.e.rose@gmail.com

Thanks,Mark

Mark Rose markrose@acm.org 925.922.7263 From: javatechs notifications@github.com To: ProgrammingRobotsStudyGroup/RobotsForKids RobotsForKids@noreply.github.com Cc: Mark Rose markrose@acm.org Sent: Monday, October 19, 2015 1:48 PM Subject: Re: [RobotsForKids] Wiki vs. Markdown Files (#5)

I invited Patrick, Jayson, J and myself to PRSG's drive. I already had the account, so adding gdox was simple.

On Mon, Oct 19, 2015 at 7:49 AM, Patrick notifications@github.com wrote:

I'd add my strong support for google docs / spreadsheets. If iGate / RG is eligible for a Google account for non-profits, this could be nice path to better collaboration tools (and it's free).

— Reply to this email directly or view it on GitHub https://github.com/ProgrammingRobotsStudyGroup/RobotsForKids/issues/5#issuecomment-149237721 .

— Reply to this email directly or view it on GitHub.

j12y commented 8 years ago

I shared it with you @merose.

pryme commented 8 years ago

Am I right to assume that we can use this for all the PRSG activities, e.g. the ROS ROV REV2 design? We could use separate folders.

javatechs commented 8 years ago

Yes. Let me know and I'll set up folders as needed. On Oct 19, 2015 6:43 PM, "Patrick" notifications@github.com wrote:

Am I right to assume that we can use this for all the PRSG activities, e.g. the ROS ROV REV2 design? We could use separate folders.

— Reply to this email directly or view it on GitHub https://github.com/ProgrammingRobotsStudyGroup/RobotsForKids/issues/5#issuecomment-149397305 .