We must organize the doc

@davidep
The problem is to find the Howto on the community because not every instruction was market as an Hoto. Also is no table of contents where you can search. OK you will say use the search function. The problem with the search function is if you use the wrong word you will not find it.
The same with ‘google it’ help. Yesterday I was on the way to install the email package. I didn’t know what the LHA option and I google it. The first pages are all about "Local Housing Allowance (LHA)’. Not helpful at all.

I see the wiki as a organised plase where you can find the approved Howto and additional information like TCP/IP, Gateway, abbreviations (I have it still on my to do list) and links.

Currently we have that Official manual which is written initially from developers, generally the module/core developer. Anytime people from the community could submit a pull request and improve manuals.
Also we have howtos here on community, created and maintained by users and now the wiki, docs from developers.
We certainly lack getting started tutorials, use cases of some modules, examples, screenshots, so we need more community docs written by users :smile:

1 Like

As II already said, there’s various type of documentation:

  • The technical reference doc.
  • The user’s manuals.
  • How Tos
  • Installation guides
  • Quick sheet.

Normally, all these documentations are for any type of audience, newcomer until the more skilled developer… It’s a very waste field.

I don’t like the idea of “official” doc vs “community” doc, It’s a dangerous game that will give more problem that resolving problems :unamused:
I would like that Dev team and Nethesis produce the “technical Reference Documentation”, and let the community fill the rest.

Let organize what we already have, and we will see what are the empty fields…

Naturally, more things will come, like newcomer howtos, and advandced module making… :grinning:

Dokuwiki and Discourse are two distincts tools, to make two distincts tasks… One is not to replace the other one.

Don’t forget that we are in the same boat, wth the same objective: Spread the world, attract more users, make NethServer easy.

4 Likes

I was looking one more time this great How to:
http://www.nethserver.org/dokuwiki/doku.php?id=howto:create_a_nethserver_virtualbox_instance

And I heve few observations:
Pictures size are not stantardized… At the beginning they are small, at the end the are medium.
And I ask: Why not put them In the bigger size? They will appear in the same size as the wiki size column.
I think the result will be better, will a better feeling :wink:

The idea behind having “official” docs is that it is created by certified people and has quality control on it so you know the documentation is accurate and complete.

Of course the community documentation should also, but in my experience community docs are (although intentions are honest and much appreciated) not always accurate and complete.

Maybe it’s the (main?) task for the docs team to make sure that documentation gets a certain level of quality that it can compete with “official” docs.

2 Likes

I think the docs team and the official docs are the same :wink:

Excuse my ignorance. Still learning about the community structure. I am coming from Zentyal and there the ‘official docs’ were maintained by the Zentyal company and the community docs… by the community.
Thnx for clarifying…

1 Like

Please, don’t apologize :slight_smile: I only expressed my idea!

I think we are a work-in-progress and the community is structuring itself.

As a developer I try to keep the documentation up-to-date, but I feel I’m not a good English writer. I would be grateful to anyone who helps me by reviewing it, fixing my mistakes and filling the missing parts.

I want to take the current development/testing workflow as a model. After a new feature has been implemented we always have tests to execute, translations to update and documentation to write. I’d like a Doc Team involved into the development process by reviewing documentation pull requests. What do you think?

3 Likes

excuse me, maybe I’m missing something but just read it now…
do you mean that wiki won’t be public?

I love ( more than like) this idea.

Why? Because I a old developper who don’t develop anymore since a long time.
I thinking that be involved in the Documentation process, I could actualise myself and finally, could make the tweak I want ( left menu, and a Netatalk module). Even If I’m not a native english speaker

The wiki is public, try it yourself :wink:
I think @alefattorini made a little mistake :smile:

I know it’s public, but Alessio’s sentence was confusing me…

Yes, my mistake :frowning: . Everyone can write but he should be previously registered and approved by docs team.

I change with a 500 px size. For me it look well balanced.

What do you think?
Can we standardize this size?

Pretty fine @Jim I like them.
With this size for images starting from a 19" monitor they are readable and not intrusive.

1 Like

I just changed the wiki URL to: http://wiki.nethserver.org/

I would like to give the official go to the wiki. What is missing?
Who want to be in charge of this?

@alefattorini @davidep @Jim @sitz @robb @zamboni @WillZen @fasttech @stephdl

1 Like

I would like to be one of who will be in charge of the wiki, I think…

I need to register myself on wiki site right?

Yes, you can also login with github :smile:

1 Like

Hummm…perhaps better.
Thank you Giacomo.