xoops forums

vamptrix

Theme Designer
Posted on: 2016/6/27 8:30
vamptrix
vamptrix (Show more)
Theme Designer
Posts: 424
Since: 2008/5/3 1
#1

Modern documentation about general usage / People needed

Hello everybody,

Currently, work is underway for XOOPS 2.6, and in order to get documentation ready before it's release we should start working on the documentation now - XOOPS 2.6 changes so many things that I feel it's best to start over with the documentation (with the exception of the existing documentation on GitBooks).

I suggest (but this is entirely open for discussion) that we use Sphinx/ReadTheDocs to create this documentation - this is a modern system that's used by quite a lot of projects, it delivers clean and easy to update documentation and it has search capability. I think this is the perfect solution to get new documentation out. What do you guys think about this?
One handy thing is that we can provide a copy of the documentation with the XOOPS download package itself.

I've been really busy over the course of the last year. Before this period I started working on documentation already, but that was focussed on XOOPS 2.5.x - but since 2.6 is coming closer it might be better to start over again and create entirely new documentation.

I can't do this entirely on my own though - so if you want to help me create this new documentation, please feel free to do so.

Kev

Mamba

Moderator
Posted on: 2016/6/27 9:13
Mamba
Mamba (Show more)
Moderator
Posts: 10988
Since: 2004/4/23
#2

Re: Modern documentation about general usage / People needed

Thank you for your willingness to help with the documentation.

Of course, we'll be glad to help with the documentation, but you need to start with it, so then we can see where we could help...

And what's wrong with GitBook?

- One single, easy to read and write, Github rendered source format (i.e. Markdown) for different output formats such as HTML, PDF, MOBI, EPUB,

- A documentation build is triggerable via Github Webhook, i.e. you can edit the documentation either with the GitBook Editor and it will upload the changes to GitHub, or you can make the changes on GitHub, and it will trigger rebuild of the book, so the readers will always have the latest and greatest version of the book, and you can choose whatever method you prefer to make changes.
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

vamptrix

Theme Designer
Posted on: 2016/6/27 10:48
vamptrix
vamptrix (Show more)
Theme Designer
Posts: 424
Since: 2008/5/3 1
#3

Re: Modern documentation about general usage / People needed

Quote:

And what's wrong with GitBook?

- One single, easy to read and write, Github rendered source format (i.e. Markdown) for different output formats such as HTML, PDF, MOBI, EPUB,

- A documentation build is triggerable via Github Webhook, i.e. you can edit the documentation either with the GitBook Editor and it will upload the changes to GitHub, or you can make the changes on GitHub, and it will trigger rebuild of the book, so the readers will always have the latest and greatest version of the book, and you can choose whatever method you prefer to make changes.


The big issue with GitBook is that it's a book: it's hard to search inside of it, and if you need information about something, it's hard to find it (unless you know how or where to find it/in which GitBook it is).
GitBook is really good for specific information about 1 thing, like a module. But for general documentation, e.g. setting up your site, getting your rights set up and all basic XOOPS things, I think that a Sphinx documentation site would be better.
Examples of Sphinx documentation are CodeIgniter, ReadTheDocs etc. It's really clean, fast and easy to maintain/edit.
And you can export it to HTML too.
And the search is really good too ;)

Mamba

Moderator
Posted on: 2016/6/27 11:45
Mamba
Mamba (Show more)
Moderator
Posts: 10988
Since: 2004/4/23
#4

Re: Modern documentation about general usage / People needed

Quote:
The big issue with GitBook is that it's a book: it's hard to search inside of it, and if you need information about something, it's hard to find it (unless you know how or where to find it/in which GitBook it is).

It seems to me that you didn't spend any time of GitBook

Why are you saying that it's really to search inside of it???? What is wrong with the search inside a Gitbook?

And if you want to link several GitBooks into one, you can do it as well. The process is the same everywhere else:

a) you can have several small books, or
b) you can create a one monster book

Quote:
And you can export it to HTML too.

What do you mean by that??? The Gitbook is HTML as default:
https://xoops.gitbooks.io/xoops-installation-guide/content/
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

vamptrix

Theme Designer
Posted on: 2016/6/27 15:20
vamptrix
vamptrix (Show more)
Theme Designer
Posts: 424
Since: 2008/5/3 1
#5

Re: Modern documentation about general usage / People needed

Quote:

Mamba wrote:
Quote:
The big issue with GitBook is that it's a book: it's hard to search inside of it, and if you need information about something, it's hard to find it (unless you know how or where to find it/in which GitBook it is).

It seems to me that you didn't spend any time of GitBook

Why are you saying that it's really to search inside of it???? What is wrong with the search inside a Gitbook?

And if you want to link several GitBooks into one, you can do it as well. The process is the same everywhere else:

a) you can have several small books, or
b) you can create a one monster book

Quote:
And you can export it to HTML too.

What do you mean by that??? The Gitbook is HTML as default:
https://xoops.gitbooks.io/xoops-installation-guide/content/


It looks like I lept to conclusions too soon - I have used Gitbooks before, but it didn't work as well back then. It look like it has improved quite a lot :)

I take back all my problems with Gitbooks ;).

vamptrix

Theme Designer
Posted on: 2016/6/30 7:33
vamptrix
vamptrix (Show more)
Theme Designer
Posts: 424
Since: 2008/5/3 1
#6

Re: Modern documentation about general usage / People needed

Mamba, could you add my user "kevinpetit" to the XOOPS organisation?