Season of Docs Lessons Learned 2019 - Revision history

Wiki-Camerons: /* Finding motivated contributors */

2020-01-26T01:34:24Z

Finding motivated contributors

Wiki-Camerons: /* Finding motivated contributors */

2020-01-26T00:45:07Z

Finding motivated contributors

Wiki-Camerons: /* Key open-source themes */

2020-01-25T20:33:16Z

Key open-source themes

Wiki-Camerons: /* =google docs - pros and cons */

2020-01-14T19:30:25Z

=google docs - pros and cons

Wiki-Camerons: /* Development Phase */

2020-01-14T19:29:59Z

Development Phase

Wiki-Camerons: /* Development Phase */

2019-12-08T06:31:11Z

Development Phase

Wiki-Camerons: /* Volunteers welcomed */

2019-05-29T08:53:44Z

Volunteers welcomed

Wiki-Camerons: /* Doc license */

2019-05-23T22:08:06Z

Doc license

Wiki-Camerons: /* Volunteers welcomed */

2019-05-23T12:46:11Z

Volunteers welcomed

Wiki-Camerons: writer exploration section

2019-05-22T07:55:47Z

writer exploration section

@@ Line 109: / Line 109: @@
 Software developers write great open-source software because they are both competent (as developers) and motivated (with an itch to scratch).
-The challenge we face with open source docs is that it is hard to find people who are both competent and motivated.
+The challenge we face with open source docs is that it is hard to find people who are competent, have an itch to scratch, and are not faced with a significant barrier to entry (for the person's skill profile).
 ===Software users:===
@@ Line 144: / Line 144: @@
 Interest in TheGoodDocsProject:
 * We have attracted multiple VOLUNTEER tech writers to help create writing templates as part of [https://thegooddocsproject.dev/ TheGoodDocsProject].
-* Tech writers are scratching an itch - such templates will help address challenges writers face on a daily basis.
+* In this case, tech writers are scratching an itch. The templates they've been motivated to create will help address challenges writers face on a daily basis.
 ==Barriers to entry==

← Older revision		Revision as of 00:45, 26 January 2020
Line 102:		Line 102:

	==Finding motivated contributors==		==Finding motivated contributors==
		+	A goal of SeasonOfDocs is to "bring open-source and technical writer communities together, to the benefit of both. Together we raise awareness of open source, of docs, and of technical writing."
		+	To realise this goal, let's consider the motivations of people involved. As explained in Eric S Raymond's first rule of open source in [http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s02.html The Cathedral and the Bazaar]:
		+
		+	''# Every good work of [open source] software starts by scratching a developer's personal itch.''
		+
		+	Software developers write great open-source software because they are both competent (as developers) and motivated (with an itch to scratch).
		+
		+	The challenge we face with open source docs is that it is hard to find people who are both competent and motivated.
		+
		+	===Software users:===
		+	Interest:
		+	* Often are very appreciative of the free software that developers have given them and want to give back in some way.
		+	* Have often been frustrated by poor documentation.
		+	* After finding a solution, are often prepared to write up a specific doc problem.
		+	* Might be prepared to write up a doc section if they feel it would be helpful and appreciated.
		+
		+	Hindered by:
		+	* Technical ramp-up required to learn to write docs (such as git, wiki markup languages).
		+	* Lack of writing experience, experience with style guides, document structures, etc.
		+	* Lack of understanding of the documentation strategy and what sort of documentation should be written.
		+	* Often don't feel worthy to provide contributions. "Developers know the software better than I.", "I'm not a trained writer."
		+
		+	===Software developers:===
		+	Disinterest:
		+	* Would prefer to write code.
		+
		+	Hindered by:
		+	* Lack of writing experience, experience with style guides, document structures, etc.
		+
		+	Interest:
		+	* Often acknowledge the importance of documentation and would like to see their product as being polished.
		+	* Might be suffering from frustrated user community asking questions because they can't find good docs.
		+
		+	===Technical Writers===
		+	Disinterest:
		+	* Typically are not users of the open-source application, so haven't used the documentation and haven't experienced a driving itch to fix them.
		+
		+	Interest Google Season of Docs:
		+	* Have joined Google Season of Docs, maybe wanting to learn about open source, maybe because they are getting paid, maybe because working on a sexy Google project is interesting or would look good on the resume.
		+
		+	Interest in TheGoodDocsProject:
		+	* We have attracted multiple VOLUNTEER tech writers to help create writing templates as part of [https://thegooddocsproject.dev/ TheGoodDocsProject].
		+	* Tech writers are scratching an itch - such templates will help address challenges writers face on a daily basis.

	==Barriers to entry==		==Barriers to entry==

← Older revision		Revision as of 20:33, 25 January 2020
Line 104:		Line 104:

	==Barriers to entry==		==Barriers to entry==
−
−	~~=Key open-source themes=~~
−	* It is all about collaboration
−	* The health of the community behind the project is more important than the technology. A healthy community will solve technical problems.
−	* Sustainability
−	* Modularity
−	* Inflection points
−	** from individual to a group
−	** from startup, focusing on features, to quality focusing on process
−	* Grit
−	* Maintaining momentum
−	* Work within a gift economy
−	* Meritocracy
−	* Do-ocracy
−	* Respect and support
−	* Diversity
−	* Time-shifting work and communication (email lists are great)
−	* Bouncing ideas off people
−	* Transparency
−	* Increasing signal-to-noise ratio
−	* Motivation
−	** Vision
−	* Innovation
−	** Innovation labs is a myth
−	** There are more people in the rest of the world trying to solve your problem than you can ever find in your team.
−	* Measurement
−	** Measurement and assessment is time-consuming
−	** We use trust metrics
−	** It helps to create trust metrics

@@ Line 87: / Line 87: @@
 ===git - pros and cons of git===
 ===wiki markups - pros and cons===
-===google docs - pros and cons==
+===google docs - pros and cons===
 ===gitdocs===
 gitdocs looks promising. Has anyone tried it and can report back?

@@ Line 83: / Line 83: @@
 [[Category: Season of Docs]]
-==Writing tools are painful==
+==Writing tools don't match writing workflows==
 Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.

← Older revision		Revision as of 06:31, 8 December 2019
Line 69:		Line 69:
	I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)		I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)

		+	= Development Phase =
		+	== Problems Open Source doc teams face ==
		+	I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.
		+
		+	* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744
		+	* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html
		+
		+	There are lessons in here which I think should be absorbed into Season of Docs:
		+	* Docs should start with an information architecture
		+	* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].
		+	* Community leadership is really important.
		+	* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].
	[[Category: Season of Docs]]		[[Category: Season of Docs]]
		+
		+	==Writing tools are painful==
		+	Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.

← Older revision		Revision as of 08:53, 29 May 2019
Line 49:		Line 49:

	We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.		We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.
		+
		+	== Communication Overload ==
		+	=== FAQ ===
		+	Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.
		+
		+	=== Project Description Overhead ===
		+	With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects?
		+	# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.
		+	# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.
		+
		+	=== Applicant Overload ===
		+	We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:
		+	# Ask applicants to respect the time of projects.
		+	# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)
		+	# Are you interested in volunteering, if so, then have a look at this separate list ...
		+	# ...

	== Doc license ==		== Doc license ==

@@ Line 51: / Line 51: @@
 == Doc license ==
-I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs.
+I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)
 [[Category: Season of Docs]]

← Older revision		Revision as of 12:46, 23 May 2019
Line 49:		Line 49:

	We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.		We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.
		+
		+	== Doc license ==
		+	I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs.

	[[Category: Season of Docs]]		[[Category: Season of Docs]]

@@ Line 34: / Line 34: @@
 ==Deadline straight after public holiday==
 The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.
 [[Category: Season of Docs]]