forked from opencultureagency/Open-Documentation-Guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
text-ODG-back.txt
311 lines (187 loc) · 14.8 KB
/
text-ODG-back.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
#ASKnet
Access to Skills and
Knowledge Network
OPEN SOURCE
DOCUMENTATION
GUIDE
#ASKNET PROGRAM
ACCESS TO SKILLS AND KNOWLEDGE NETWORK
#ASKnet provides access to skills and knowledge to empower youth,
Address community challenges and transform cultural patterns.
#ASKnet (Access to Skills and Knowledge Network) is a capacity building and hub development program linking six community based youth-led innovation hubs in South Sudan, Uganda and Kenya. The #ASKnet community aims to build a sustainable network of trainers and empowered individuals, to address challenges their communities are facing and transform cultural patterns that fuel conflict and inequality. Providing youth access to skills and knowledge, Training of Trainers (ToT) workshops in open source hardware and software using #ASKotec, entrepreneurship,media production, gender equality awareness, trauma healing and financial literacy. #ASKnet innovation training is a initiative by r0g_agency for open culture and critical transformation (Berlin), funded by the ‘Access to information and Supporting Freedom of Expression’ program of the German Federal Ministry of Economic Cooperation and Development (BMZ).
This Open Source Documentation Guide aims to help you understand what you can do to prepare real open sourse documentation, how you come up with open source solutions, finalized products and overcome challenges in process and methods.
There are many different reasons to document you work, process, product or invention: for experts, learners, social media team, documentation team, PR, funding and to invite people to work with you on developing the project, hardware or software further.
#ASKnet
Open Source
Documentation
Guide
GitHub Repository to add info and contribute:
Github.com/opencultureagency/Open-Documentation-Guide
CREDITS
Project by: (r0g agency logo)
In partnership with: (Hive COLAB logo)
With financial support from the: (Federal Ministry for Economic Cooperation and Development logo)
#ASKnet Hubs:
CC-BY-SA 4.0! This work is licensed under the terms of:
Creativecommons.org/licenses/by-sa/4.0/
Published by r0g_agency for open culture and critical transformation gGmbH
Under a creative commons Attribution-ShareAlike 4.0 International license. Version 1. 2020
WHY OPEN SOURCE DOCUMENTATION?
Share your knowledge with the world!
To build up free knowledge for everyone.
Open source helps with access to information in fragile or post-conflict scenarios & areas where you need to build up infrastructure fast and increase capacity. Strengthen your local community and join forces with an international open source alliance!
Be clear on WHY do you do it and able to explain that.
Increase the momentum of innovation with collaborative development & gain access to resources, tools and knowledge by sharing your work.
Connect to the community that is going to use and help develop it.
Find communities that are already using these tools and platforms
Accessibility – you will need to provide a clear structure and give details on how to contribute to the project.
Talk to people, share examples and knowledge.
By collaborating publicly everyone contributes their own resources to the project. Especially in cases where you don’t have all the knowledge or skills to finish a project, it’s the best way to get it done. If you want to save resources by not reinventing the wheel, the best way is to join forces and collaborate. Avoid complicated contracts with an open source license, and share your work with everybody who wants to participate.
DOCUMENTATION SCENARIOS & COMMUNITY
What to document so everyone is on board?
Understand the structure of information and processes to explain what you have made. Understand how open source documentation works so you know what to keep in mind: eg, file types, templates, formats, video/photo text/diagrams, step-by-step instructions.
• processes, tools, readme files
• How to contribute to this project
• Platform choice to collaborate
• Back-up structure to do documentation
Know what to keep in mind:
Eg. File types, templates, formats, video/photo text/ diagrams, step-by-step instructions.
Open Source Guide to Building Community
Open source guide/building-community/
>>Good documentation only becomes more important as your community grows. Casual contributors, who may not otherwise be familiar with your project, read your documentation to quickly get the context they need.<<
>> Your README is more than just a set of instructions. It’s also a place to talk about your goals, product vision, and roadmap. If people are overly focused on debating the merit of a particular feature, it may help to revisit your README and talk about the higher vision of your project. Focusing on your README also depersonalizes the conversation, so you can have a constructive discussion.<<
Opensource.guide
Any questions that comes up in the process might be relevant for collabrators so include answers to these in you documentation!
GLOSSARY OF TERMS
CodiMD: Open source platform to write & collaborate on markdown text to host on your own server and that you can use for free. https://github.com/codimd/server https://demo.codimd.org/
HackMD: Closed source markdown platform similar to CodiMD.
Markdown: Lightweight markup language with plain-text-formatting syntax. Easily written and displayed by lots of platforms. Because of its simplicity it’s useful for documenting your user guides, meeting minutes and readme files. Not meant for layout/design!
Issue: When something isn’t working, alert the developer to fix it! When you find something that can be improved, suggestions to make or general technical issue.
Feature request: Special type of issue report that shares ideas to improve the project.
Fork: When you copy all the files of a project into a new repository, name it and create your own new offshoot – make the changes yourself.
Issue tracker: Management area for your issues.
Telegram: It’s a text based messenger that you can use to share files, management teams, have news channels, to help organize your project.
GitHub: It’s a text based collaboration platform, that allows you to shae the source (code/text/files) of your work and invite other people to adapt, develop, work on it and contribute to new versions!
>>(/grt/): is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. << /Wikipedia
GitLab: An open source example of git based development platform – mainly software, can be used for hardware and open source project. You can work on decentralized, personalized project on these platforms. More tools you can use for free.
The magic about git is you can work on your computer locally, and push it later to the repository. The platform is the project & file management front end, where you track issues, and feature requests, manage you community and collaborate with the team.
Repository: A place where your files sit/are stored/but also shared… Public Open Visible. Keep a local copy of your files on your computer, especially when using any online/cloud platform or demo version.
Wiki: A website or database developed collaboratively by a community of user, allowing any user to add and edit content. Wiki is also a Hawaiian word which means “fast or quick”.
Creative Commons Licenses
A set of rules you can choose from to release your creative work. Some of the CC options are open source licenses, like CC-BY or CC-BY-SA where BY=attribution, and SA=share alike. Creativecommons.org
“That’s what the magic is about open source! You can take multiple ideas, realized – although your idea takes a new path from the original. Whenever you fork something and you IMPROVE it by adding features or new design. Always link back to the original design. In case you fork something, make it known. Look at the license that it has and follow the terms and conditions of license before you start!” Timm Wille
HOW TO MAKE IT OPEN SOURCE?
Use an open source license!
There are different types of Open Source Licenses to choose from.
COPYLEFT LICENSES
>>Copyleft or Viral licenses allow anyone to use, explore, distribute or modify the projects, but you must publicly contribute and commit all the modifications that you have made to the original project. The original project is kept updated, and it has evolved. A person or organization using or depending upon it is legally bound to share their own modification, help maintain the project, and contribute to the updates.<<
CC-BY-SA 4.0
Creativecommons.org/licenses/by-sa/4.0/
CERN Open Hardware Lic.
www.ohwr.org/project/cernohl/wikis/home
GPLv3
Tldrlegal.com/license/mozilla-public-license-v3-(gpl-3)
Mozilla Public License 2.0
Tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)
PERMISSIVE LICENSES
>>permissive licenses allow creators to release a project as open source so anyone can explore, use, modify and distribute it in any way. Also known as “copyright licenses”.<<
Apache 2.0
www.apache.org/licenses/License-2.0
CC-BY 4.0
Creativecommons.org/licenses/by/4.0/
MIT License
En.wikipedia.org/wiki/MIT_License
If you choose CC-NC Non-commercial or ND – no derivatives – these restrict use and remix of the project. Therefore it is NOT Open Source. Also, if you don’t choose any license then you have not given permission for anyone else to adapt or use your work.
FILE FORMATS & TIPS
Share your source files: everything you need to collaborate without reconstructing the whole thing.
Understand what platform to use (versioning*):e.g. GitLab, Wikifactory. Version control allows you to keep track of each new contribution and releases! *Each change is embedded in history of repository.
DESIGN
SVG – open illustration format
JPG & PNG (these are OUTPUT formats) – understand the best practices to save, name and share your actual source files!
TECHNICAL FILES
CAD Files – technical drawings
STEP/STP & SVG – interoperable formats in case your working file is not open software based STL.
PNG & PDF – provide platform independent viewable formats to enable more people to read, understand and share the project/concept. (For each release!)
WORDS
Text files –
Odt / docx / txt / pad / Readme
BINARY FILES
Videos, photos and other big sized files (e.g. non-text-based, packaged) should either be outsourced to an upload platform (Cloud, Video platform etc.) or kept to a minimum.
TO DO’S AND TO DONT’S
gdoc
to gdoc or not to gdoc? Why use/don’t use? (issues for privacy, google using your data as product, force you to sign up with email address to participate)
Privacy
Data issues – open source doesn’t mean you share everything, need to protect the privacy of other people
Contribution
List to see who put what effort into x project – git based documentation let’s you see who did what in terms of project – if you make a product or service for instance.
OPEN SOURCE HARDWARE & THE LICENSES
• How do you open your work to collaboration?
• Does it make sense to use a git, cloud server or wiki?
• Where do you want to “host” your community?
• What are the steps to make contributions open?
What are you sharing?
Is it documentation of a product, technical process, hardware, software (sourcecode), concept/idea, book, training module? Understand the framework you need based on the open tools available.
The main thing is you always share the “source code” that means all your working files that you use to create this output: that means technical drawings & CAD models, text and svg files for design layout.
What type of content are you documenting?
This will define what tools, platforms or processes to use!
Examples for platforms according to use-case
• Open hardware & software ‘source code’ repository for files )original, versionised, compare): Github/Gitlab
• Step-by-step Instructions: wikifab/wikihow
• Text based collaboration: etherpad, codimd
Create a visual process
Show technical diagrams, illustrations, roadmaps
>>An open source project with no license attached – no matter how remarkable it is – is avoided for use by everyone. For others to use, distribute, and build upon projects the creator must have first given their express permission outlining use of their designs, constituting it as open source. No license, in practice, means you are abandoning your work in the wild instead of owning it and sharing with others. <<Usama Abid on Medium
Open by license:
Medium.com/inventhub/open-source-hardware-the-licenses-a244733e6cb7
The “Recipe” for an Open Documentation
EXAMPLE: REPAIR CAFÉ
• Select you project to document: in this case, electronics or hardware repairs.
• Create a guide, simple how-to repair radio, mobile phone or how to use a soldering iron etc.
• Technical examples, diagrams, outline steps and give overview for the basic process.
This event involves hands on use of tools to repair broken appliances. The #ASKotec materials will come in handy, as people who have their appliances or electronics broken see the repair process and learn the skills to repair their gadgets next time. Document the event on Wikifab.
WHAT IS A REPAIR CAFÉ?
Repair Café is a space to repair broken electronic appliances of the public. Ranging from phones, radios, television and solar panels and more. The Repair Café as an open source documentation scenario combines training, workshop and event aspects. Trainers help community members evolve within their sessions.
TOOLS
• #ASKotec kit
• Soldering iron
• Hands
• Camera
• Computer/laptop
MATERIALS
• Soldering wire
• Wires
• Soletape
• Masking tape
• Internet
• Pens and
• Notebooks (Documentation)
SERVING SUGGESTION
Audience
Build your community, people with repair needs, keen to learn or create spaces for community interaction, socially & ecologically minded!
Resources:
Repaircafe.org
Get more insights via
Wikifab.org/wiki/repair_Cafe’
METHOD
Instructions to make it tasty!
• Team Setup
Provide Blueprint of space, briefing teams
• Space Setup (repair/maker space)
Reception team near the door / entry Expert tables (U/C Shape)
Waiting Space / Community Management
• Registration Process
Register devices under the owners name Tag devices with sticky notes and numbers Sort devices that can/can’t be repaired
• Repair Process
Tool Keeping &maintenance
• Education
Share the skills and steps required to do this at home!
• Documentation
Documentation & list of all repairs to track success Statistics – repairs completed, diagrams, pictures.
• Social Media
Share Repair Café success stories on your social media channels. Use hashtags #ASKnet #RepairCafe.
#ASKnet Open Training on GitHub
Expamples of other training content:
OPEN TRAINING GUIDE
How to set up your own training formats
Github.com/opencultureagency/Open-Training-Guide