Topic: Merge documentation and develoment pages

[Muzo]

Hello,

I saw 2 pages : Documentation and Developpement, twice have same kind of informations : HowTo's.
And it's worse in French, nothing in Documentation, too many things in Developpement.

May some clean these page or merge it?

P.S.: Nobody can change this pages, but only people how locked it can!

[RonM]

Please post links to the pages you're talking about, so we can take a look

[Muzo]

These pages are :
http://no.longer.valid/phpwiki/
http://no.longer.valid/phpwiki/index.php/French%20documentation
http://no.longer.valid/phpwiki/index.php/Development
http://no.longer.valid/phpwiki/index.php/D%E9veloppement

[RonM]

Sorry, Muzo, but I just can't see what is wrong with the two English pages ( I can't read the French ones)

The Documentation page has sections for beginners, Installation, The manuals, Searching, Contribs, Misc and Wiki, and is focused on end-user/admins. The Development page has Guidlines, Tools, Bugs, Upcoming Releases, and the Manual, and is focused on developers (Core and add-ons)

They both do have links to manuals and Howto and Contribs - this is just a convenience.

Both pages could certainly be improved - for instance, I'd like to see more of a seperation between 'contrib' development and 'core' development on the dev page. I always figured the developers themselves would suggest any changes they felt desireable.

[wellsi]

I also believe that improvements can be made, maybe we need to brainstorm this a bit.

Muzo, do you want to make a suggestion for how it should be organised and then we can go from there to come up with something more consistant and easier to use.

These pages have been growing over time so a fresh look at this may be in order.

Ian

[Muzo]

Ok, i'll post here a suggestion later (not enough time now)

Stay tuned

[Muzo]

Ok, i found 5 minute. I made a merge of all ideas.

Documentation page, it must be same structure for all language.

1- Basic Documentation

- Introduction
- Design Philosophy
- Architecture overview
- KeyConcept
- GPL

Installation

- Getting started

Manuals

- Manuals SME 5.6
- Manuals SME 6.0-contribs

FAQ

- Administration FAQ
- Installation FAQ
- Security FAQ
- Dysfunctions FAQ

Help

- Newsgroups
- Forums
- Irc
- Contribs.org mailing lists
 * Subscription
 * Devinfo
 * Discussion
 
How To's and Contribs

- HowTo's
- Contribs
- weblinks

2- Linux Documentation

Developpement page, the best one is english one, but i add an introduction (same page as Documentation, to remember SME's architecture)

Introduction

- Design Philosophy
- Architecture overview
- KeyConcept

Development Guidelines

Development Tools

Bugs

Upcoming releases

Manual

Contact

(contact list like devel@contribs, volunteers@contribs, ... )

[RonM]

OK, I made a temp example of a new documentation page (for discussion) here http://no.longer.valid/phpwiki/index.php?pagename=Temp%20Doc

This has some duplication of the nav bar, etc., but that's not necessarily a bad thing. It'll draw people's attention to the highlights.

What this does do, though, is repurpose the page more toward existing users. That's ok too, but I think we should talk about it. For instance existing users need the wiki doc stuff. Also, I think more explanatory text should be added - for instance the devinfo link needs to be carefully handled.

[RonM]

And A Dev page here:
http://no.longer.valid/phpwiki/index.php?pagename=Temp%20Dev

Both follow Muzo's suggestions above.

Suggestion:
Let's talk about what we want these pages to do, and how, here.

[wellsi]

How To's and Contribs

Maybe this should be a link to the ContribsPage (and some explanatory text) rather than the three links.

I would like to see the
New contrib Announcements - Let the community know about your contribs and How Tos!
Near the top of the ContribsPage (as that does seem a more logical place then the DocPage). It could also have a link on the development page if we think of it as 'Current Development' - we don't need to use this name but thinking in this way means that it is relevant for the Dev page.

I think all of the wiki info could go/stay at the bottom.

Most importantly for me are the RecentChanges/Edits links. Maybe we should link to How-to%20Classification%20Admin and make more active use of it (link to it also from the site-work list etc)

I notice that the manuals are referenced from both pages, but the 'new' manual is only on the docs page.

The volunteering page should be linked from the Dev Page.

Some quick thoughts, however I need to think more when I am more awake.

(On the Dev page there should be a link to the DevTools)

[RonM]

Good thoughts, esp. if you're asleep

Before we get too deep in the details, though, it seems to me some more general ideas are in order

like, who are our users for the doc page? the dev page?
what kinds of things do they need to see for each?

should we try to get detailed links and explanations on each page, or general links to specific topic pages or what?

should we try to align the English and French pages, or not?

etc.

[wellsi]

Before we get too deep in the details, though, it seems to me some more general ideas are in order

Yes - I was unhappy with my post for exactly that reason. Tomorrow I'll think.

[RonM]

I updated the pages with something like Ian's suggestions above.

[wellsi]

My thoughts:

--

Doc page is for SME Server Users who want to find out how to use SME Server. One part missing is how to make use of SME Server - I know that a very long time ago there was the sme_101, 201 idea which would be ideal after the Getting Started.

Doc Page is not for the Doc Team & Volunteers maintaining the documentation, there should be a seperate page for that linked from here.

Doc Page does not need a link to any email lists, there are no lists for 'end-user' support. Instead the forums & on-line help are provided.

The link to contribs is valid as the end-user wants to bolt on another black-box.

I think that this page is mainly used when making use of SME Server. A person does not care how it actually works (just a black box), instead they want to get a job done.
--

Dev Page is for developers of SME Server, either contribs or core developers. It should include information on how to modify or make RPMs, detailed information on how SME Server works, also how SME Server is being developed (Roadmap),and the Bug List. It should include links into the deveopment community, this means that it links to the Volunteering page, the experienced forum, DevInfo & Discussion email lists - but not Doc list.

It has the guidelines on how to build & submit a contrib. Also how to propose changes in the core, either package changes or how to cope with forks.

Personally I would look at this page to find the dev tools, understand how the guts of SME Server work, and how to feed things back to the community.

This page is used when you want to understand how a task is actually carried out so that you can change it.
---

Some information will always be a bit of both, but I think that we should try to avoid overlap where possible.

---
A minor detail point

To volunteer to help out at Contribs.org, please use the Volunteering page

I think that the text is wrong, it implies that the page is for helping out at contribs.org (the site). Maybe '...at Contribs.org or in developing SME Server, please...'

Ian

[Muzo]

I agree Wellsi.