Development Introduction

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 'Source Code Management', 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 version control system Subversion. To get the most up-to-date version of the documentation, run this command in a terminal window:

svn checkout https://responsibility.svn.sourceforge.net/svnroot/responsibility/documentation/

More information about how to work with the version control system is found in the guide Source Code Management. There it is also described how to commit changes. The same technique applies to the documentation.

When you execute the "svn checkout" command, it will create a new folder called documentation in whatever directory (folder) you were in when you ran the command. For many systems, this is the 'home' folder by default. The documentation folder contains 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

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 documentation/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 be found on the regular website, as well as shipped with the source code tarballs. 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 may use the ./generate script in the 'documentation' folder to generate documents from the 'page' files. First though, you'll need to open the script file in a text editor and change the three variables, POCO_BASE, DOC_BASE and NR_BASE, according to wherever you've put the POCO files, the documentation files, and the Net Responsibility files. Once that's done you can use a terminal window and enter the 'documentation' folder (using the cd command as shown above) and run the script 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. 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, 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.