We must organize the doc

Community
1

Hello,

With discourse, we have a funny tool to make conversations, to exchange ideas, make debates… And for now make howtos.

But Discourse with all it’s qualyties is little flat… I mean, it lack a way to structure the iinformation, all is on the same plan.( it’s 2D), and when an Howto is posted…with the time it will be down, down, down…you will need to scroll, scroll, scroll to find it.

With the upcoming wiki :grin:
We will have lot of more perspectives, and I suggest to already organize all the existing Howtos published here. How ?

I suggest to organize the existing howto retagging them this way:
How to contribute, yes there’s various ways to contribute ( develop, make doc, report bug…).
How to community ( organization, the teams presentations, and teams rules , tools, sitesA… )
How to dev corner,
How to Ui ( can be a sub cat of the precedent one)
How to E-smith ( can be a sub cat like the precedent one)
How to App ( for all type of… Applications, like Roundcube, Sogo, Girafa, Plex, Owncloud, and so on…)

Sure, there’s other ways to tag, like adding the level ( general audience, intermediate, high skill), and it’s not the definitive structure of the wiki… It’s simply a way to start doing the upcoming wiki, start organize.

There’s a subliminal message in the topic
wanted information knowledge idea

2

I just had a quick search on Discourse and saw that the wiki discussion goes back to 27th of February this year. That’s almost 9 months! In this time the community wasn’t able to come to a decision what to use for documentation.

What I understood there are several options:

  • Keep going on with Discourse
  • Install Mediawiki and switch to that.
  • There is Redmine which has a built in wiki module
  • Use Github as base for documentation

All options have pro’s and cons. My opinion is that the option to choose is the one that does the job best. What I have seen of Discourse is that is is great for forums, but less equipped for documentation.
I know Redmine is quite good. I used it when I was with Zentyal community. But if tracker and repo is moving to github, what is the use of keeping an extra, heavy application? Github has also its limitations. That leaves Mediawiki… :wink:
Maybe we should look for a wiki that makes it possible to use Discourse accounts so some kind of SSO can be used?

1 Like
3

As I was saying on the other thread, let’s start by organizing the HowTo collection using ReadTheDocs!

I think some of the “categories” proposed by Jim should go to www.netheserver.org web site:

  • community structure, teams,
  • organization rules,
  • pointers to documentation and bug tracker.

on docs.nethserver.org (ReadTheDocs):

  • Administrator Manual
  • Developer Manual
  • HowTo Collection

Everyone can contribute to the main web site contents and the doc bundle if we adopt a GitHub-based workflow as we’re doing for the source code.

2 Likes
4

Ok, let’s go for Readthedoc.

But, can you repeat where is the entry exactly… It’s not very clear yet.
http://dev.nethserver.org ?
http://docs.nethserver.org ?

5

Are you ready to modify a howto with a pull request from github…except if i’m wrong this is the way you are agree to go…it is a developer way you will have only to add some words in a howto

6

Yes…or dokuwiki, that’s the way to go

1 Like
7

Agree, anything-wiki

Dokuwiki and Mediawiki compare in WikiMatrix
http://www.wikimatrix.org/compare/dokuwiki+mediawiki

8

@davidep Do you tink that people will go into the process of doing the github way when contributing to documentation? Personally I have great doubts and fear that it is too complicated for community members. It will result in a very small group of contributors and will exclude a large group of potential document writers.
I know mediawiki/dokuwiki has a learningcurve too, but I really fear that the learningcurve for github is too steep for most people.

9

Looking at the features Dokuwiki looks more interesting. Especially the ACL option that is lacking with mediawiki is important.

10

I love mediawiki but I do admit that dokuwiki is much more easier to use and maintain

11

I’m thinking about the great work of the Translation team, that edited on GitHub the Spanish manual translation. It shows it is possible even for non-developers to collaborate in such way.

@jgjimenezs, @mabeleira what do you think of your experience?

Furthermore, as @alefattorini said, the community already contributed a lot of HowTos on Discourse. What we’re missing now is an index of those documents, the “table of contents” and - above all - somebody who takes care of designing it!

We must organize the doc is the perfect title for this thread. We must focus on team organization, I think the tools are already available. I can help to set up ReadTheDocs!

3 Likes
12

Hi @davidep

GitHub is very easy to work as in transifex.

I was going to do a manual from ReadTheDocs.

13

Hi paisano. I agree with it.

Transifex is wonderful. You can even synchronize with Github By webhook , according to a Colombian friend tells me .

The great thing is that many people come to translate into their native language voluntarily.

1 Like
14

Hi Friend, this week, i’ll call you.

Regards.

1 Like
15

Just split it and i’ll take a part, to help you with.

1 Like
16

who will accept and manage all pull request ?

17

The other thread is about the stuff… What to use? The choice ( the debate) is not closed yet.
This thread is about the existing doc.

I see a wiki as a way to organise the existing doc and the future doc. the link on the wiki could point on an existing address in a Discourse topic.

But perhaps there’s intermediate solution, like the Knowledge base.
Like this: http://community.ubnt.com/t5/tkb/v2/communitypage

What do you think about a simple page, under the Doc team responsibility to organize, with linked discourse howtos topics?

Edit: it can be a link to a discourse topic, but a link to a youtube channel too…

18

Where is the Howto Team?

I would like to know the point of view members of this Team…

19

this is a post of @AbsyntH who was not able to post a howto in discouse, he needed to use pastebin → bind9+facileManager webui

discourse is a forum, not a wiki

20

That’s odd, I CAN! :smiley:

Alias /facileManager /var/www/html/facileManager
<Directory "/var/www/html/facileManager">
  AllowOverride All
 
</Directory>