Documentation

Contents

The need for good documentation

Good documentation is crucial for all kinds of software. If you're having a hard time installing and getting a program working, and there's no good documentation, you'll just give up and go looking for a different program, right? On the other hand, if there is good documentation available, you'll likely manage to set it up and then everyone is happy.

Unfortunately, open source projects tend to lack good documentation, since the programmers are more concerned about the coding. It is also often presumed that the users are comfortable with compiling and have a basic understanding about programming. This is certainly not always the case.

It is actually even better if the creator of the documentation is not the programmer. The more involved one is in the nuts and bolts, the more likely it is that important questions will be neglected because they may seem obvious. The ideal documentation author is often someone not involved in the actual programming, but who still has an ongoing dialogue with those who are. However, anyone is welcome to contribute, since the goal is to create documentation that is as clear and up-to-date as possible, and of course we'd like your help!

Getting started

Of course, you may contact us and say something like "I think you should change the words 'blah blah blah' in paragraph 3 in the page called 'Ten Steps to NR Happiness', to 'losum ipsum'." We can take care of it from there. It would be even better though if you followed these instructions, since this will make it easier for all of us in the long run.

The documentation, like the rest of the source code, is handled by the distributed version control system (DVCS) Mecurial, and hosted at BitBucket. In order to contribute to the documentation development, you will need to have Mercurial installed on your system and have a BitBucket account (individual, not team). If you are unfamiliar with Mercurial, this basic tutorial will help you get started with it. If you're new to BitBucket, you will find this guide helpful. If you're interested in using a graphical interface rather than the command-line, we recommend TortoiseHG.

One of the advantages of a DVCS like Mercurial is an easy and reliable system for creating branches off of the main repo and then later submitting those changes back to the main repo, which provides more freedom and flexibility in development. An advantage of BitBucket is that you can also fork a repo, which also gives more flexibility. We recommend that NR developers use BitBucket to fork a repo, and then clone that forked repo to their systems to serve as a local repo. To create a fork, log in to BitBucket, go to the NR documentation repo page, click on the 'Fork' button, and enter the necessary information, etc. to complete the process. Once you've done that, here is a sample of the terminal command you would use (from within the desired directory) to clone your new fork to your local system (you will need to replace <path/to/forked/repo> with whatever the path is to your forked repo on BitBucket):

hg clone <path/to/forked/repo>

If you go to the BitBucket page of your forked repo, you can also just click on the 'Clone' button and copy the command from the window that opens.

More information about how to work with Mercurial and BitBucket is found in the Repository Management guide. There it is also described how to submit changes to the main repo.

When you execute the terminal command above, it will clone (create) a current copy of the NR documentation repo in whatever directory (folder) you were in when you ran the command. For many systems, this is the 'home' folder by default, but you can choose to put it wherever you want. The repo folder will contain several subfolders, described briefly as follows:

cfg - Config (configuration) files (with .xml extension) used when generating the documentation from the page files (with .page extension).

doc - When the documentation is 'generated' from the page files, it creates HTML files here that can then be opened with a web browser to see how they will appear to the user.

pages - The raw pages where all writing and editing happens, and that will then be used to generate the documentation.

resources - Images, stylesheets etc. that are used in generating the documentation.

If your primary goal is creating and editing documentation, then you will only need to work with the files in the 'pages' folder, which can be opened and edited in your choice of text editor. However, you may also want to set up your system to generate documents and then access the files in the 'doc' folder to see how the pages you are working on will appear to the user.

Guidelines

General

When you edit the 'pages' files, you will want to use a text editor that allows you to apply word wrap, which ensures that each line of text is around 80 characters long. While you may not notice a difference on your own system, this will help make the documentation and the changes you've made easier to read in certain environments, such as on BitBucket or when using Mercurial-related tools. When applying word wrap, make sure that links are not split across lines; otherwise they will not show up properly.

Syntax

Once you get going the syntax will be pretty easy to understand. The first two lines in the document contain the title and the category. The title should explain briefly what the page is all about. The category must follow the guidelines described below.

Next you can divide the page into smaller sections (depending on the size, of course). Each section should have a large heading (!!!Large heading), and may also contain smaller headings if appropriate (!!Medium heading, !Small heading). The headings will also be displayed on top of the page, and serve as a table of contents. Choose names here carefully.

The paragraphs are divided by blank lines. More examples on how to add links, images, bold, italic text, etc. can be found in the file pages/samplePage.txt or by looking in some of the other 'page' files that include whatever you are wanting to use.

Bold vs. Italic

Be careful with using bold text. If you want to emphasize something, please do so in italic. This is more natural for the eyes, but the point is still clear. In some cases you may find it more appropriate to use bold text, and it's not forbidden, but be careful with it.

Categories

All pages are grouped into categories. The names of the categories can be found in the config files (in the 'cfg' folder), in a section that looks like this:

<A01NR_Appetizer>Appetizer</A01NR_Appetizer>
<A03NR_Install>Installation and Configuration</A03NR_Install>
<A07NR_ForAP>For Accountability Partners</A07NR_ForAP>
<A09NR_FurtherReading>Further Reading</A09NR_FurtherReading>
<A50NR_DevIntro>Development Introduction</A50NR_DevIntro>

You may find the tag names awkward at first, but there is a reason they're named like this. We want to separate the Net Responsibility (NR) pages from the POCO-related pages, and we want them to show up in the correct order. The beginning 'A' is to put it above the POCO-related pages, and because XML doesn't allow us to use a number first.

The numbers used in the category abbreviations have a little gap between them to make sure there's room to add more categories later on if we want. All categories with a number less than 50 are considered to be user documentation, and will show up on the regular website. All categories with a number of 50 and above are considered to be documentation for developers only. These pages can include more technical (i.e. 'geekier') language, and writers can take more knowledge for granted. These pages will only be displayed in the Developers Documentation.

'NR' in the category name just makes it clear that this is part of the Net Responsibility documentation.

Everything to the right of the underscore is just an abbreviation of the full category name. It needs to be obvious what it's supposed to abbreviate.

Filenames

The filenames must follow a certain pattern, like this page that's named '5004-Documentation.page'. The first two digits are the category number. Since this page is a part of 'A50NR_DevIntro', the number is '50'.

The next two digits make it clear what place the page should have in the ordering of pages inside the category.

After the dash comes an abbreviation of the title. The same thing applies here as with the category abbreviation explained above — it needs to be obvious which title it abbreviates, so one can easily find the right file to edit.

Generating the documentation

Note that you may contribute to the documentation without generating it.

The documentation is generated (i.e., converted into HTML, making it viewable in a web browser) with a utility called PocoDoc. To be able to use it, you'll need to compile it together with the rest of POCO. To do this, first extract the latest version of POCO (the basic edition is okay to use), putting its contents in a folder of your choice. Then you need to go to that folder, open the file called 'components' in a text editor and add the following two lines to it:

CppParser
PocoDoc

Once you have done this, save the file. Then open a terminal window and use the cd command to put yourself in the folder where you put the extracted POCO file contents earlier. For instance, if you put the POCO files in /home/name/poco then you would use the command cd /home/name/poco to enter that folder. Once you are in the folder where you put the POCO files, run the following commands to compile POCO, download and compile PocoDoc and CppParser, and install everything.

export POCO_BASE=$(pwd)
svn checkout https://poco.svn.sourceforge.net/svnroot/poco/sandbox/PocoDoc/

./PocoDoc

svn checkout

https://poco.svn.sourceforge.net/svnroot/poco/sandbox/CppParser/ ./CppParser

./configure
make -s
make -s --directory=./CppParser
make -s --directory=./PocoDoc
make install

Make sure the last command make install is run as 'root'. In Ubuntu/Debian this means using sudo and running the command as sudo make install . Other Linux systems might use su in the same way. The main thing is that you need to run the command as 'root', however your particular system handles that.

Once you've successfully compiled and installed PocoDoc, you will want to make sure that PocoDoc will be able to access the needed NR source code when it generates the documentation. First, you need to make sure you have a clone of the NR software repo on your system. If you don't already have a local NR software repo or if you need a separate one, you can clone one by following the instructions in the Getting Started section of this document, but using the NR software repo page instead of the NR documentation repo page. If you will only be using this local NR software repo for generating documentation and not for doing any development on the NR source code itself, then you can simply do a clone of the main NR repo without first forking a branch. Secondly, because a newly cloned local repo represents the latest development version of the NR software, you need to make sure it is updated so it represents the correct version/release you are generating documentation for (this will normally be the latest stable release). To update the repo to the latest stable release, run the command hg update stable in whatever directory it is located. Then, each time a new stable version is released, you will want to make sure and pull all the changes from the main repo to your local repo in order to update it. You can run the command hg pull && hg update to both pull the changes and then update your repo with them. If you ever want to confirm what version of NR your local repo currently represents, you can open the configure.ac file in that directory and look at the line near the top that starts with 'AC_Init'. This line should include the version number in brackets.

Now that you have PocoDoc installed and your local NR software repo set up, you are able to use the ./generate script in the NR documentation repo directory to generate documents from the 'page' files. The first time you run the script, you will be asked to enter the paths of three different variables, POCO_BASE, DOC_BASE and NR_BASE, according to wherever you've put the POCO files, the NR documentation repo, and the NR software repo. This will create a file in the same directory called paths.txt that stores the paths you entered. You can later use a text editor to open this file and make any necessary changes, or if you delete this file, you will be prompted to enter the paths again the next time you run the script. Once you've entered the correct paths you can use a terminal window and enter the directory where you cloned the documentation repo (using the cd command as shown above) and run the script from there with the following command:

./generate [cfg file]

Where [cfg file] is the name of the config file to use, excluding the file ending. For instance, to use cfg/DevDocs.xml, just run

./generate DevDocs

Once you've successfully run the script, you should find the HTML files that were generated in the 'doc' folder, and can open them in a web browser to see what they look like, which is helpful for testing purposes. If you only want to generate documents from 'page' files (it will take less time to run the script, and may be all you need), you can use the 'PagesOnly' config file instead of 'DevDocs' when running the script.

Troubleshooting

If you are having problems with getting set up to help contribute to the documentation or have related questions, please let us know, and we'll do our best to help you figure things out. This dialogue may also help us know how we can improve the information and instructions on this page.