Make knowledge findable

[gvwilson]

• Make sure newcomers know where to look for what
  • Everything doesn’t have to be in the same place, but every thing of a particular kind should all be in one place
  • "Someone mailed me your tweet about the Slack discussion so I filed a GitHub issue about updating the Google Doc we use to keep track of our wikis. Wait, why are you crying?"
• Pick a small number of channels
  • Are you using Slack, emails, a forum, or issues/comments on GitHub as your main channel?
• Make everything searchable
  • Using general-purpose search engines like Bing and Google as well as in-page search for your site alone.

[igorsteinmacher]

When starting their process to contribute to a project, newcomers need to learn about the project. However, newcomers to software projects are akin as explorers who must orient themselves within an unfamiliar landscape [1]. Thus, it is important to make sure that all necessary information is accessible, or at least searchable, by the newcomers during their first steps.

Spread information usually make newcomers feel lost and disoriented. Given the different possibilities of places to maintain information (e.g., wikis, files in the repository, shared documents), it is important to keep information about a specific topic consolidated in a single place, so developers do not need to navigate multiple data sources to find what they need. The literature has shown that organizing the information make newcomers more confident and oriented [2]. This organization is something important for technical and process documentation but also for communication channels. Thus, another suggestion is to keep a small number of communication channels, and clearly define the goals for each of them.

Outdated documentation, differently, may lead newcomers to a wrong understanding of the project, which is also demotivating. In many cases it may be hard to keep documentation up-to-date, community members should remove outdated information or, at least, clearly identify it as outdated. Making newcomers aware of the absence or the status of a document can save their time and set their expectations. By recognizing the obsolescence of the information, communities may request help from the newcomers as a way to foster their contribution.

[1] Dagenais B, Ossher H, Bellamy RK, Robillard MP, De Vries JP. Moving into a new software project landscape. InProceedings of the 32nd ACM/IEEE International Conference on Software Engineering-Volume 1 2010 May 1 (pp. 275-284). ACM.

[2] Steinmacher I, Conte TU, Treude C, Gerosa MA. Overcoming open source project entry barriers with a portal for newcomers. InProceedings of the 38th International Conference on Software Engineering 2016 May 14 (pp. 273-284). ACM.