Contributor Hubs, group all interesting ressources for contributors

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
Mika38
Posts: 45
Joined: Fri Feb 10, 2017 10:29 pm
Location: Swindon, Uk - from France

Contributor Hubs, group all interesting ressources for contributors

Postby Mika38 » Sun Mar 26, 2017 10:51 pm

Dear contributors,

I think we all agree that we would love to have new contributor in FreeCAD. There is certainly all lot of people how would like to contribute to FreeCAD, but I think the first steps are really hard to achieve. For example, before modifying the wiki a new contributor need to 1) create an account in the Forum 2) post a message to ask for a wiki account 3) get validated 4) get use to the wiki interface 5) Improve the wiki by translating or creating new pages. In my knowledge, this procedure is not on the wiki. I think you can agree that it can discourage someone which just want to correct a typo error, but if this persons find a wiki page with clear information of all those steps, he or she will probably find the energy to change this page.

Now that this post is introduced, let's see what already exist and how improve the current situation.

Currently, There is one post in the forum which help to get started: How to get wiki editing permissions https://forum.freecadweb.org/viewtopic.php?f=21&t=6830. A post on the forum then link to https://www.freecadweb.org/wiki/WikiPages. This "wikipages" is a great resources and contain most of the information necessary to start contributing to the FreeCAD documentation. In my knowledge, there is no, easy-to-find link to access this page from the main page. Also, I think this page should be factorize: 20 sections, It's too much, and it contains off topic information (ex: 16 Sandbox Macros recipes). In my knowledge, there is no information to how is the best way to promote FreeCAD.

In short my proposition is: regroup most of the contributor resources on the wiki. A good way too achieve this group would be to create a "Contributor Hubs" in the https://www.freecadweb.org/wiki/Main_Page. Then, modify and if necessary create several pages to initiate the new contributor. It should not be redundant with the developer hubs, so in this hubs, any thing linked to writing a line of code would just point to the right developer section. Idem with macro and the Power users hub.
I though about those pages for a start:
- How to make your first improvement of the wiki?
- How to translate a page? (already exist in developer hubs could be place here)
- How to create a new wiki page?
- Most of the different section of the https://www.freecadweb.org/wiki/WikiPages deserve there own page: wiki writing style, add illustration, wiki structure, etc..
And because contributing is not only about coding and improving the wiki:
- How to promote FreeCAD? (list of argument in favor of FreeCAD, marketing material, it could link to presentations, external articles for example)
- How to share a video of FreeCAD? (video tutorial are great to promote the use of FreeCAD, which are the good practices? Where to share on FreeCAD forum? Where to create a link on the wiki? which software to record ...)
- How to report a bug? (The report bug page in developer section could be place again here, because this page is relevant to the programmer profile and the non-programmer contributor)
- How to give feedback to the FreeCAD community? (where to place testimony of your experience, Who and where to ask for a new feature, where to share a great idea, etc...)
- Next events related to FreeCAD (if exist)

I don't want to redo any thing which is already done. I would like to gather on this message the different resources at the disposition for the contributor. I'm quite new here, so I don't know everything about FreeCAD contribution, so don't hesitate to share unquoted resources in your reply. I will than edit the list below:

wiki pages:

Main current resources: WikiPages https://www.freecadweb.org/wiki/WikiPages
Translating FreeCAD https://www.freecadweb.org/wiki/Localisation
Find assistance (bug track) https://www.freecadweb.org/wiki/Tracker
Contributors (list of contributors) https://www.freecadweb.org/wiki/Contributors
Category:UnfinishedDocu https://www.freecadweb.org/wiki/Category:UnfinishedDocu
Wanted pages https://www.freecadweb.org/wiki/Category:UnfinishedDocu

Forum post:
How to get wiki editing permissions https://forum.freecadweb.org/viewtopic.php?f=21&t=6830
Request for collaboration: Creating a visual flow chart for reporting bugs https://forum.freecadweb.org/viewtopic.php?f=34&t=20804

Other site link to FreeCAD:
https://github.com/freecad/homepage

Do you think it's a good idea? Should it be done an other way?

Do you know any other resources that I did not quote? I will edit the list.
edit:
- add github, UnfinishedDocu, Wanted pages
Last edited by Mika38 on Thu Mar 30, 2017 11:25 am, edited 3 times in total.
;) Le chemin est long, mais la voie est libre :D The journey is long but the way is free 8-)
User avatar
kkremitzki
Posts: 1796
Joined: Thu Mar 03, 2016 9:52 pm
Location: Texas

Re: Contributor Hubs, group all interesting ressources for contributors

Postby kkremitzki » Sun Mar 26, 2017 11:09 pm

I think creating a "Contributors hub" page is an excellent idea.

This page is definitely good to include:
https://www.freecadweb.org/wiki/Tracker

for people who want to help out by testing or organizings bugs or feature projects.

It would probably be good to include information about https://github.com/freecad/homepage and ways people can contribute to the site infrastructure.

Links to contributing things like artwork, icons, etc. would also be good.

Having some sort of table overview of modules/pages needing documented would also be good; a sort of central place to organize outstanding work in the wiki.
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
User avatar
r-frank
Posts: 2181
Joined: Thu Jan 24, 2013 6:26 pm
Location: Möckmühl, Germany
Contact:

Re: Contributor Hubs, group all interesting ressources for contributors

Postby r-frank » Mon Mar 27, 2017 8:15 am

Hello.

Well, i agree that gathering/organizing the Information how to contribute on "user-level" or "non-programmer-level" is a VERY GOOD
idea. Thanks for taking initiative for a first start.

Missing Points on your list:

Since the wiki can't host FreeCAD-files, this Github-repository was created.
I think that most of the tutorials should have example files hosted there.
If you get stuck you can download the file and have a "peek" how it should look like ...
I will try to update the readme.md as fast as possible showing Information on how to add new files to the repository ...
[Edit] Done ...

Information on how to contribute to translations in case of stable release via crowdin.
This is a complex thing and will require a lot of Information to be gathered.
But even the longest journey begins with the first step :D

We could mention "low hanging fruits" in the wiki pointing to the pages
Wanted Pages
Category: Unfinished Docu

Especially bringing down the number of hits in "unfinished docu" to a reasonable amount would be a big step forward.
Next step would be increasing the number of 100% translated pages ...

I am using my personal "discussion" page as a reminder/to-do-list.
I am listing there findings of missing informations, really-need-to-be-improved-pages and so on.
It would be great to find a way to "centralize" these informations (bug tracker is too high-level for that) ...

Roland
Deutsche FreeCAD Tutorials auf Youtube
My GrabCAD FreeCAD-Projects
FreeCAD lessons for beginners in english

Native german speaker - so apologies for my english, no offense intended :)
renatorivo
Posts: 2259
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: Contributor Hubs, group all interesting ressources for contributors

Postby renatorivo » Mon Mar 27, 2017 7:00 pm

kkremitzki wrote:I think creating a "Contributors hub" page is an excellent idea.
+1

"Contributors hub" might be confused with "Developers hub", "Wiki contributors hub", "Wiki hub" ??

Renato
User avatar
r-frank
Posts: 2181
Joined: Thu Jan 24, 2013 6:26 pm
Location: Möckmühl, Germany
Contact:

Re: Contributor Hubs, group all interesting ressources for contributors

Postby r-frank » Mon Mar 27, 2017 7:03 pm

renatorivo wrote:Wiki contributors hub
That sounds really good ...
+1
Deutsche FreeCAD Tutorials auf Youtube
My GrabCAD FreeCAD-Projects
FreeCAD lessons for beginners in english

Native german speaker - so apologies for my english, no offense intended :)
renatorivo
Posts: 2259
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: Contributor Hubs, group all interesting ressources for contributors

Postby renatorivo » Mon Mar 27, 2017 8:47 pm

or organize in this way?
schema.png
schema.png (3.04 KiB) Viewed 1966 times
User avatar
Mika38
Posts: 45
Joined: Fri Feb 10, 2017 10:29 pm
Location: Swindon, Uk - from France

Re: Contributor Hubs, group all interesting ressources for contributors

Postby Mika38 » Mon Mar 27, 2017 10:46 pm

@renatorivo last post +1
It is this approach that Inkscape choose. Link: https://inkscape.org/en/contribute/
;) Le chemin est long, mais la voie est libre :D The journey is long but the way is free 8-)
User avatar
Mika38
Posts: 45
Joined: Fri Feb 10, 2017 10:29 pm
Location: Swindon, Uk - from France

Re: Contributor Hubs, group all interesting ressources for contributors

Postby Mika38 » Thu Mar 30, 2017 11:22 am

As I send before I do not what to start from scratch. So we already have lot of bit and pieces to assemble all in the first post. Here, I'm going to make a short review of How different community trying to get more developer. This is my personal analysis, I'm writing it here first because it help me structure my though and second because it should be interesting for you. I will sum-up what I learn from this review and what are my recommendation for FreeCAD contributor/Get involve page.

Benchmark, what are the other communities are doing? I picked different communities:
-4 references in the freesoftware community
-One video game
-2 Extremely technical

And, I will detail the best one I found:

Example of "Contributor Page" from other Free-Software community (comment) link:
Mozilla (very very high quality, Please note that there is no motion of code at all) https://www.mozilla.org/en-US/contribute/ Detail analysis after:
Inkscape (A good quality goal, formating close to our wiki, have a look) https://inkscape.org/en/contribute/
Webdev/GetInvolved/mozilla.org (good quality) https://wiki.mozilla.org/Webdev/GetInvolved/mozilla.org
Blender get involve (Simple, ok, no promotion part) https://www.blender.org/get-involved/
Blender manuel contribute translation (counter-example, mix of Dutch and English) https://docs.blender.org/manual/de/dev/ ... ibute.html
Blender manuel (simple, no sharing) https://docs.blender.org/manual/en/dev/ ... index.html
SuperTuxKart Get involve (Only link, but nice layout: (For programmer, for artiste, for everyone))https://supertuxkart.net/Community
Anjuta Development (Only code related, no design, no promotion, no human)http://anjuta.org/development/
lineageOS Community (almost nothing, 4 links, no appealing)http://lineageos.org/community/
Krita Get Involved (Great layout, Intro, Developer and non-developer, suggestion, bug report, donate. Recommended) https://krita.org/en/get-involved/artists/

Let's try to sum-up what I learn by reading all those site. All those project have an active community. Most of then, insist on the programming part, except Mozilla. Mozilla contributor page is so unique a detail analysis is done after. Most have proposition for non-programming volunteer, Anjuta is a good example of project only focus on code. Basically, Anjuta seems to recruit only code-expert. Mozilla go a step forward and propose an emotional experience to connect the reader with the community, using video, stories, and proposition of event. Krita and Inkscape are more classic, nevertheless they are appealing for a new members. Special mention for Krita gallery section and Inkscape promot. Those pages are worths to see, those pages give ideas of easy to achieve action for new comers. I think, the first thing a new volunteer want to achieve is some thing which will impact for the project in a good way. To propose simple action inkscape have this page: Inkscape's Community To-Do List.

Let's no speak about the bad stuff, the worst I saw was the anjuta wall of fame. Imagine you are a women from China, who want to get involve in a project, you discover that most of the member do not look like you at all and doesn't have your profile. In my opinion, you with your background will not feel welcome at all. In comparison, Mozilla, give an example of diversity, show the face of multiple profile and background. An other bad example is blender translation page: this page is not even well translated. Do you imagine a new comer feel in front of a tutorial like that?

Detail analysis Mozilla get involve page:

Three different widgets : Why volunteer Find an event Meet Mozillans

Why volunteer widget:
1- statistic of number of contributor:
"Volunteer with Mozilla!
10,554 active Mozillians worldwide 37 upcoming events around the globe 87 languages and counting, on every continent"
1- 3 animated picture with short sentences and "Get Involve" button
2Bis- Get Involve subpage: 3 "Try something simple" project to participate and 3 "Try something more challenging", with great layout
3- Video with simple content: show diversity of community: "I'm a mozillan" repeated 40 times, create emotional connection with high beat music, Leader speech, mozilla logo. In conclusion a really good ad.
4- "How Mozillians help every day": 3 faces of actual volunteers, there name and link to there story (see Meet Mozillans bellow)
5- "Join a global community of game-changers." same get involve button
7- "Not ready to dive in just yet? ":
four links: Donate to Mozilla Download Firefox Like us on Facebook Follow us on Twitter
8- Other info: Upcoming event Communicate (list communication tools) More links:
Submit Firefox feedback
Explore Mozilla careers
Get help with Firefox
Subscribe to community events
Get community updates (sign up for email list)

Find an event widget:
List event with : Date Event Location

Meet Mozillans widget:
1- Statistic of mozilla community
2- #IAmAMozillian and explanation of the slogan
3- On image of a volunteer is name, a short story, a list of contribution project, 3 different ways to contact the volunteer
4- "Meet a few more Mozillians" Proposition of 3 other stories

To sum-up Mozilla get involve, proposed an emotional experience of 5min which end up by either clicking on 1 of the 6 projects proposed behind the get involve button, or donation or promotional inscription to mail list. The user is carry by the hand. A video give flashing positive image of diversity. Story telling allow user to place them self in the position of a contributor, and multiple way are offer to basic user to start to be part of the community: social media, mail letter, events.

Proposition for FreeCAD contributor page:
In construction

to go futher, see intro video of Blender conference 2016 : https://www.blender.org/conference/2016/
;) Le chemin est long, mais la voie est libre :D The journey is long but the way is free 8-)
User avatar
Mika38
Posts: 45
Joined: Fri Feb 10, 2017 10:29 pm
Location: Swindon, Uk - from France

Re: Contributor Hubs, group all interesting ressources for contributors

Postby Mika38 » Sun Apr 02, 2017 3:38 pm

I this post I will present the further research result I had since last message.

Because, I did not know any thing about documentation design, I made some research. I remembered a video of FOSDEM 2017 linked to user oriented design. Interviews as user research | How I built a public transportation UI using interviews. In this video, a designer wanted to make a new user interface for the gnome UI. He start sharing with is girlfriends and realized he needed more input to create the new UI. He then conducted interview post-process the result under the form of "personna". Those personnas are some kind of generic user with name, background and user need. I really like the idea.
I really liked the idea of user oriented design. I think that the development of FreeCAD does seems to be driven by the user needs. For example, I don't know if there is any statistic about the users, a summarization of the needs of the user, and what are the features desired by users.
This video and all the video from the Open Source Design devroom of the FOSDEM 2017 where all interesting; so, I searched if they was any presentation talking about documentation. Does someone know how to do a better contributor documentation? I limited the research to the FOSDEM 2017.
I found this interesting video about the two different way of creating a documentation: Bridging the Gap between Legacy Docs and Modular Content. I really liked his presentation of the two models. The first classic way of creating a documentation is to list all the feature inside a program, like in out user hub. He calls it Legacy Docs. The second way, which is the solution he proposes, is user experience linked. Different guides of the most commune user experience are created, they don't cover all the functionalities but the are very details to the core functions and easier to maintain. He call it Modular Content. In FreeCAD doc, we can see this type of approach in the great The FreeCAD manual.
The modular approach seems to be well though. Simplicity seems to be embedded in the design. It create better results because it's shorter, easier to read and complete for the majority of the user. This approach is more focus in the creation of "how to manual" then a list of all functions. As he said in an ideal world, both types of documentations should exist.
Then, I searched to see which FOSS project the speaker, Robert Kratky, is taking part. And he is working for Red Hat, for the documentation of Fedora. And I looked, if by any chance, there contribution documentation were well made. I found this one: Fedora Contributor Documentation | Translation Quick Start Guide. This documentation is extremely concise and go directly to the essential.
I also fall in love with the fedora main project join page. There is so much stuff which are good in those pages. First and main concept, they identify 6 types of Roles:
  • Content Writer
  • Designer
  • People Person
  • OS Developer
  • Translator
  • Web Developer or Administrator
. Those roles are really generic, and can easily be transpose in FreeCAD. Then, for each role different projects are proposed, with for each one a step by step tutorial to get involve. This lead to the creation of big page like this one https://fedoraproject.org/wiki/CommOps or smaller one like this one https://fedoraproject.org/wiki/Ambassadors_Join_start. To sum-up, Fedora's contributor page is a great example we should follow.
More research could be done on other free OS, by lake of time the research is stop here.
Next step: I'm please to tell you that I'm confident enough to make a detail architecture proposition for the FreeCAD's contributor hub, when I will have the time. It will mainly base on fedora join page with elements of Mozilla page, and other concept.
;) Le chemin est long, mais la voie est libre :D The journey is long but the way is free 8-)
User avatar
Mika38
Posts: 45
Joined: Fri Feb 10, 2017 10:29 pm
Location: Swindon, Uk - from France

Re: Contributor Hubs, group all interesting ressources for contributors

Postby Mika38 » Sun Apr 09, 2017 3:44 pm

Here is my proposition for the contributor Hubs. First in this message I explain how I came to this proposition, then there is the Transition proposition and an long term proposition.

Because changing the documentation should be a smooth process. Let’s get two different step. As saw before there is some kind of attachment to the Developer Hubs page. So, let’s keep it as it is for the moment and focus on what is lacking from the current wiki. There is no centrals hub for non-developer contributors. In that hubs should be listed all the different place and tools already in-place for them.
Concerning the way the information should be shape. I’m propose to do only tutorial pages in this part. This way, new comers will have a clear step by step instruction to get started. In my opinion, the more classic way which is an article which point to different resources is harder to maintain and to read. I think that what a contributor wants is to get there hand dirty, and they want there first action to have an impact. So prove my point that a tutorial is the way to go, let’s look at two way to get information about VPN: if you compare those two pages:
https://en.wikipedia.org/wiki/Virtual_private_network, http://www.wikihow.com/Use-a-VPN which one will make you get started the fastest way? Which one will give you a better overview of the technology? So, in my opinion a step by step will be more useful for our contributors. Now imagine the contributor workflow change. Refactoring the article page is really time consuming, however by changing steps in a step by step should be easier. For other part of the documentation this approach I think could be counter productive, but for this part it is the way. More info on the previous messages.
In a long term perspective, I would love to see the developer hubs integrated inside the contributor hubs, because it will shows to every new comers that we value as much a non-technical help than a technical one. There for, the community should expend more easily. However, because the current community is mainly composed of developer there is no point of shadow them.
I tried to find all the user case link to the current and future development of FreeCAD. Then, I create a title to different “How to” guide. I don’t really know the workflow on FreeCAD so I made supposition. And I predicted how the contribution will improve. To share my vision of what should be they are all listed after. One step at the time, I propose a transition proposition, which contain short time achievable objectives.

What do you think of the transition proposition? Should I go forward with that? Do you think proposing step by step tutorial is a good idea? Do you have idea of other guides which could be useful? @r-frank, @renatorivo and @kkremitzki

Transition proposition:

User Hubs
Power user Hubs
Contributor Hubs (centralized for non-code related)
  • Introduction
  • 6 roles in same page
  • Add tutorials each time they are created
Developer Hubs


Priority: one tutorial for each role, with intro, how to get started, list of other resources no included before.

Long term proposition :

Contributor Hubs:
Statistics of contributions
“Get Involve” button
Promotional Video of FreeCAD community
Three stories of contributors
“Get Involve” button

Contributor Roles
How to donate for FreeCAD
Content Writer
  • How to correct a wiki page
  • How to complete an unfinished page
  • How to create a new page
  • How to create a tutorial
  • How to contribute to the forum
  • How to create a video about FreeCAD
Designer
  • How to share your creation
  • How to create promotion support
  • How to work with developers
  • How to improve the interface
  • How to implement a new workflow
  • How to improve the behaviors
  • How to propose a long term objective
People Person
  • How to help other users
  • How to become an ambassador
  • How to share your experience
  • How to represent FreeCAD during an event
  • How to increase the Press coverage
OS Developer
  • How to report a bug
  • How to have an overview of the development
  • How to build FreeCAD
  • How to fix a bug
  • How to make a Unitarian test
  • How to take part of a project
  • How to make your first code contribution
  • How to document a new feature
  • How to ask for feedback
  • How to make a user-test
  • How to improve the interface
Translator
  • How to improve the translation of a page
  • How to translate an entire page
  • How to translate the user interface
  • How to add a new language in the UI
  • How to create a section of your language in the Forum
Web Developer or Administrator
  • How to improve the website
  • How to take part of the infrastructure maintenance
  • How to participate in the creation of a foundation
  • How to take part at the create of a FreeCAD blog
  • How to help with FreeCAD legal issue
;) Le chemin est long, mais la voie est libre :D The journey is long but the way is free 8-)