GNU Astronomy Utilities


Next: , Previous: , Up: Developing   [Contents][Index]


11.5 Documentation

Documentation (this book) is an integral part of Gnuastro (see Science and its tools). Documentation is not considered a separate project and must be written by its developers. Users can make edits/corrections, but the initial writing must be by the developer. So, no change is considered valid for implementation unless the respective parts of the book have also been updated. The following procedure can be a good suggestion to take when you have a new idea and are about to start implementing it.

The steps below are not a requirement, the important thing is that when you send the program to be included in Gnuastro, the book and the code have to both be fully up-to-date and compatible and the purpose should be very clearly explained. You can follow any path you choose to do this, the following path was what we have found to be most successful until now.

  1. Edit the book and fully explain your desired change, such that your idea is completely embedded in the general context of the book with no sense of discontinuity for a first time reader. This will allow you to plan the idea much more accurately and in the general context of Gnuastro or a particular program. Later on, when you are coding, this general context will significantly help you as a road-map.

    A very important part of this process is the program introduction, which explains the purposes of the program. Before actually starting to code, explain your idea’s purpose thoroughly in the start of the program section you wish to add or edit. While actually writing its purpose for a new reader, you will probably get some very valuable ideas that you hadn’t thought of before. This has occurred several times during the creation of Gnuastro. If an introduction already exists, embed or blend your idea’s purpose with the existing purposes. We emphasize that doing this is equally useful for you (as the programmer) as it is useful for the user (reader). Recall that the purpose of a program is very important, see Program design philosophy.

    As you have already noticed for every program, it is very important that the basics of the science and technique be explained in separate subsections prior to the ‘Invoking Programname’ subsection. If you are writing a new program or your addition to an existing program involves a new concept, also include such subsections and explain the concepts so a person completely unfamiliar with the concepts can get a general initial understanding. You don’t have to go deep into the details, just enough to get an interested person (with absolutely no background) started. If you feel you can’t do that, then you have probably not understood the concept yourself! If you feel you don’t have the time, then think about yourself as the reader in one year: you will forget almost all the details, so now that you have done all the theoretical preparations, add a few more hours and document it, so next time you don’t have to prepare as much. Have in mind that your only limitation in length is the fatigue of the reader after reading a long text, nothing else. So as long as you keep it relevant/interesting for the reader, there is no page number limit/cost!

    It might also help if you start discussing the usage of your idea in the ‘Invoking ProgramName’ subsection (explaining the options and arguments you have in mind) at this stage too. Actually starting to write it here will really help you later when you are coding.

  2. After you have finished adding your initial intended plan to the book, then start coding your change or new program within the Gnuastro source files. While you are coding, you will notice that somethings should be different from what you wrote in the book (your initial plan). So correct them as you are actually coding, but don’t worry too much about missing a few things (see the next step).
  3. After your work has been fully implemented, read the section documentation from the start and see if you didn’t miss any change in the coding and to see if the context is fairly continuous for a first time reader (who hasn’t seen the book or had known Gnuastro before you made your change).

Next: , Previous: , Up: Developing   [Contents][Index]