search

AmpersandTarski / documentation

Read the documentation online:
https://www.gitbook.com/book/ampersandtarski/documentation
GNU General Public License v3.0
1 stars 2 forks source link

Move documentation to regular & github #1

Closed Michiel-s closed 9 years ago

Michiel-s commented 9 years ago

Hi Han,

It's good practice to keep the code and its documentation in one repository. Therefore I suggest to merge the README.md of this repo to the AmpersandTarski/ampersand repo.

As discussed yesterday, I will also think about the content of the doc.

See here an example of a documentation I like: https://github.com/mgonto/restangular

In our new frontend we also use that library.

Michiel

hanjoosten commented 9 years ago

Ah, I see you've found the documentation allready! :) Sooner than I anticipated. I have good reasons to have the docs in a separate repo. First of all, this isn't only about the code. I agree that as far as to document code, it should be in the source files. But that is not what this documentation will be about. More on that later. There are loads of other (great!) projects that do so too. For instance clojure There are lots more. this is a nice example of a dedicated website containing one or more (parts of) a repository's documentation. Very easy to create, and I see possibilities to automate that. So: No sweat, it has been thought about. (The latter site inspired me on the initial setup, on which you commented)

The main thing is that we have some repo(s) that contain a README.md that is complete in itself. There could be a structure of directories with 'chapters' . Each directory should again contain a README.md. etc. References in the stuff in a repo should be local, which makes everything very portable. restangular does so too. I agree that this is a nice way to go. I also had a look at other tools, like GitBook. This gives possibilities to go to other formats like pdf or whatever. This is how Scott Chacon's book: Pro Git was written.

It is up to the writers of the documentation to see if they like large README.md files with little references to chapters in it, like restangular, or useing the structure of subdirectories. Main thing is to comply at a few simple rules:

  1. Things should be easy to find
  2. be consise
  3. complete Github READMEs
  4. easy on the eye

Now let's start some ausomeness!

hanjoosten commented 9 years ago

Update: I found out, that it is VERY convenient, to use the toolchain of GitBook to edit the book. I am going to change some stuff at the configuration we have now, to enable the entire team to use GitBook as an editor, without a deep learning curve. So just hold on one or two days, until I had the chance to get it right. This is REALLY COOL stuff!

hanjoosten commented 9 years ago

I have made some notes about how the documentation is setup. It is available online . See the chapter on GitBook for details.