search

nicolasdb / nicolasdb.github.io

My portfolio website as a maker and fabmanager
https://nicolasdb.github.io/
Other
1 stars 4 forks source link

How to document with github? #102

Open nicolasdb opened 5 years ago

nicolasdb commented 5 years ago

I'll take for exemple my documentation for NDA workshop @ fab14. Which is already mess up a little bit because a closed pull request. I'll explain later here....

nicolasdb commented 5 years ago

So, as learned on the guided tutorial from lab-github. image

I first started a branch called "ndaWorkshop" to add files without messing with the "master" branch like this: image

I add me references, pictures, notes and ideas like a work-in-progress. I wanted to invite people there so we can share and discuss about this workshop. but at some point, .... I had another idea and I changed the cover of my portfolio. BUT I forgot to get back on the master to do that and the change was into this branch. problem: The change won't affect the website until I merge the branch into the "Master".

So, i did that. Thinking it will merge what I have already done and I just have to continue on the same branch to add more. Yup but I need to start a new pull request. And the old stuff is still on the other pull request, which is closed now.

Conclusion: it's not the right way to do it. (but it's ok to fail, no?) 😉 Maybe combining an issue + some pull request when we agree and merge specific changes?

Master @satblip ,what do you think?

nicolasdb commented 5 years ago

@cod3monk Julian, I'm trying to work on 2 sides here.

  1. a report for the workshop we did. (I started here, I'm working on the post right now)
  2. and kind of a tutorial to explain how to start documenting whit github.

I also asked to Charlene and Pascaline who was at the workshop too about how they document. They don't use github. And since it's not about creating a new plateforme, we could test something here and just showing what are the benefit of github.

That could be perfect to present something to fablabs.io I saw that github is talking about metadata also, here in their courses about community > https://lab.github.com/courses/community-starter-kit what do you think?

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image https://bocoup.com/blog/git-workflow-walkthrough-feature-branches

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image

  1. description following template

  2. if zenhub, use the pipeline, TODO>REVIEW>DONE image

  3. Assign to someOne

  4. Use labels to define status of the job

  5. we don't use project here yet. but could be interesting

nicolasdb commented 5 years ago

Dernier post, préciser les tùches suivante. Responsabilité: the One.

Next step: 
- [ ] Branche, résumé dans fichier .md et pull request.
- [ ] rappel facture via facturation@openfab
nicolasdb commented 5 years ago

okokok. Donc. I started with this idea. To welcome a new member on the team level. image https://www.mindmeister.com/1182777247

after an introduction, you want to join the organisation. Good, and you're welcome. But very soon, you'll come on github to select some taks on what you have the skills to help. FIRST step. how to use github? It's seems that the course 1 from lab.github is to much. There is too much concepts to understand as for a hard beginner.

like

Maybe let's try with something very result/communication oriented, the issue management. 1.4: GitHub Issues - Git and GitHub for Poets https://www.youtube.com/watch?v=WMykv2ZMyEQ

and we need something directly concrete, on the point of view of the "student", it must be directly related on what he is working. And showing an example on how someone do it. also, in the same field (kind of). To feel related and inspired.

And maybe create more analogy from how we use slack or an other platform...

gamificationLoop this shit is important. We need common ground, to feel kind of at home and very quickly get our marks. And more of that, the logic must be the same every times, at all level.

  1. you'll learn the loop.
  2. you start the master it.
  3. now you create within the loop. https://www.youtube.com/watch?v=lqoGeieNH7M https://www.youtube.com/watch?v=2z7nIDSbloc

not a loop = bad gamification. ^^ image

nicolasdb commented 5 years ago

Il faut prendre en compte la syntaxe markdown. maybe starting with that and making link with slack (I know is special flavor of markdown) and what other platform use it? for slack. https://blog.hubspot.com/marketing/slack-tips https://get.slack.help/hc/fr-fr/articles/202288908-Mettre-en-forme-vos-messages

And maybe preparing a cheatsheet for the passport. image

some tut's https://www.markdowntutorial.com/ https://guides.github.com/features/mastering-markdown/ some ref. https://carto.com/blog/why-we-use-markdown/ https://www.markdownguide.org/getting-started/ https://blog.ghost.org/markdown/

Main advantage I had read is to keep the focus of the writing. Most writers are distracted by the need to use the mouse just to click somewhere, and change styles or font. It break the flow of words. So, using markdown is an easy and a fast way to format your text.

nicolasdb commented 5 years ago

8 techniques pour enseigner avec pédagogie https://www.huffingtonpost.fr/stephane-edouard/8-techniques-pour-enseigner-avec-pedagogie_b_5392323.html

Why do we use github in Openfab? (or Vulca, or as a maker?) and how?

We need to put the accent on why and how using github as a maker and not as a software developer. There is no tutorial for casual people, non nerdy geek except the one for poets but even I like it, it's still a bit weird. We need to use analogy and make reference on more common grounds. What kind of grounds then?

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image

https://hackaday.com/2016/03/21/the-hackers-notebook-a-mission-log-for-every-project/

nicolasdb commented 5 years ago

creating your free account

  1. go on https://github.com/
  2. Fill in Username, Email and your password. And click the green button.

image

  1. Choose unlimited public repo for free. Click Continue. Github is free as soon as you keep public what you do on github. Good for opensource projects.

sign

  1. You can fill up the form or just skip the step 3.

VoilĂ , you are ready to participate in any conversation on the platform = "issues"

  1. Spend 10 minute to understand how to use Markdown syntax; it will help you to format your text. Markdown is a way to write content for the web. https://www.markdowntutorial.com/

  2. Explore our Open Issues on Vulca/coreTeam repository. https://github.com/Vulca/coreTeam/issues

To get further, here is a general overview Getting Started with GitHub https://www.youtube.com/watch?v=noZnOSpcjYY

nicolasdb commented 5 years ago

Next 102: Les issues. https://www.youtube.com/watch?v=ukYSRu4k0gs

Maybe starting with that, as a goal or teaser to understand in what way it's interesting to take the time to use this.

nicolasdb commented 5 years ago

image

Main structure of levelingUP. >bagdes

alone workflow

group workflow

nicolasdb commented 5 years ago

102 Issues

homework:

Start whith watching this: https://www.youtube.com/watch?v=WMykv2ZMyEQ

why?

I'm using issues like a way to organize my ideas and to help me documenting my projects. I just start an issue on my repo and start to describe 3 important things (COP = Context, Objectives, Proposition) then I just add comments, steps, ideas, what is working , or not, taking note, copypasta of stuffs and upload pictures, meme and most important, lol cats.

image

note: to add picture, just copypasta them in the body of comment. It will upload it somewhere and you'll be able to use the weblink in your markdown files. image

Then, let's check that: You can start by browsing issues from Vulca/coreTeam repository. Here: ../Vulca/coreTeam/issues

capture

So what is an issue?

Issue Tracker is an advanced and complete tool for tracking the evolution of a new idea or the process of solving a problem. It allows you, your team, and your collaborators to share and discuss proposals before and while implementing them from gitlab wiki

How I use them?

Issues can have endless applications. Just to exemplify, these are some cases for which creating issues are most used:

SO

“Always start with an issue” says Job, VP of Product here at GitLab. Before you begin anything else, summarize your ideas in an issue and share it. It’s such a simple rule, but the impact is huge. In this post we'll focus on issues for feature proposals specifically, but the rule applies in any case, no matter what kind of project you're working on. We say “start” with an issue and not “create” an issue, because one might already exist. Make sure to search in All issues (open and closed) to see if your idea has been proposed already. https://about.gitlab.com/2016/03/03/start-with-an-issue/

You’ve found a project you like, and you’re ready to make a contribution. Finally! Here’s how to get your contribution in the right way.
https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution

nicolasdb commented 5 years ago

I need to make a post about notification settings... It's still not very clear...

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

image

nicolasdb commented 5 years ago

I'll add a small tiny miny challenge after the 101

image

image

nicolasdb commented 5 years ago

your mission is to format your presentation like that!

image image

nicolasdb commented 5 years ago

image

satblip commented 5 years ago

https://learngitbranching.js.org/

nicolasdb commented 5 years ago

Le boss level est trop gros. Il faut trop réfléchir pour son contenu. Comment peut-on le simplifier? Qu'elles sont les informations pertinentes à transmettre, pour se présenter? Sans devoir faire une psychanalyse de son inconscient.

Une présentation de son projet, besoin au sein du lab? les inspirations?