Open Source: GitHub for .NET Developers, Part 3: Documents and Statistics
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Introduction
In Part 2 of this series, I described the steps and the tools that GitHub offers for team development and for accepting contributions to a repository from the developer community worldwide. In this final article, I'll explain how to create documentation pages inside a repository and how to analyze project activities with built-in stats.
Using Wiki Pages to Document a Repository
GitHub provides several ways to create documentation for a repository. The first method we'll examine is Wiki pages. With Wiki pages, you can write any documents you need, describing aspects of your repository. To create a Wiki page, click the Wiki tab on the repository's home page. If your repository doesn't have any existing Wiki pages, you'll be prompted with a welcome page, where you'll need to click a button called Create first page. At this point (see Figure 1), GitHub provides an editor that supports Markdown, and you can type any text you like.
)
Figure 1 Editing a Wiki page.
Click the Preview tab to see how the page will look to visitors (see Figure 2).
)
Figure 2 Previewing a Wiki page.
When ready, simply click Save Page. Notice that this is the first time you don't have to commit a file to complete your changes; the reason is simply that Wiki pages are not under source control. Pages you add will be visible in a proper list, available when visitors click the Wiki tab.
Adding Document Files to the Repository
In many repositories, such as Microsoft's .NET Compiler Platform repository, documents are organized into project subfolders, typically edited using Markdown conventions so that they can be viewed with a web browser. To add folders to your repository, open the Code tab to show the list of files, and then click New File. This action allows you to create a new file and organize your new files into subfolders. For instance, if you supply docs/Intro.md as the new filename, GitHub understands that you want to create a subfolder called docs and a file called Intro.md inside the docs folder. As Figure 3 shows, GitHub creates the subfolder and provides an editor for the new file. Of course, GitHub doesn't limit you to just documents; in fact, a very new feature allows uploading files to your repository's folders directly by simply dragging them from Windows Explorer and dropping onto the repository's home page.
)
Figure 3 Adding a new document file.
When you're finished editing the document, click Commit new file.
The benefit of using this technique is that document files can be reached via their URL and viewed with a web browser. For instance, the URL for the sample Intro.md file is the following:
https://github.com/AlessandroDelSole/FantasticLibrary/blob/master/docs/Intro.md
Here's the structure of the URL:
https://github.com/YourAccount/YourRepository/blob/BranchName/FolderName/Filename
Statistics: Monitoring Project Activities
GitHub offers useful tools for monitoring activities in a repository. One of these tools is called Pulse, which you enable by clicking the Pulse tab. With this tool, the project administrator can see how many people have contributed and with how many commits, how many issues have been managed, how many pull requests have been merged, and the time interval (see Figure 4).
)
Figure 4 Viewing repository stats with Pulse.
This tool is very useful for understanding how contributors and collaborators are working with the repository.
Click the Graphs tab to access another interesting tool, Graphs, which shows a graphical analysis of data such as these statistics:
- Collaborator activities
- Network traffic on the project page, including the number of visitors
- Number of commits per day
- Frequency of adding/removing code blocks (by week)
- Most-visited pages
- Number of forks
Figure 5 shows an example based on the collaborators' activities.
)
Figure 5 Viewing repository stats with Graphs.
This tool is particularly useful when the repository has many contributors, or if it has been forked many times.
Wrapping Up
GitHub offers a number of easy ways to add documentation to your repositories and to analyze activities.
Of course, there's much more to GitHub than the features I've explained in this article series, but you now have the basic skills to work with open source projects in much the same way as Microsoft is doing. So, don't forget to visit and bookmark the GitHub help center, which provides very accurate documentation about everything you can do with the platform.