On 9/19/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:

I would like to get the FAQ back.

A FAQ is an excellent way of knowing what are missing. Let users add questions to it, and then use that as a base to improve the documentation. I agree with that a FAQ should not be needed if the documentation is good, but since it's not complete, a FAQ is nice to information about what is missing.

The FAQ was never removed, its still there, however its not maintained like it should be. It claims certain things arent available when they have been for a year. The wiki is a community documentation project. It enables each and every one of you to not only read documentation, but also to update it and add to it. If documentation is missing, incorrect, incomplete then anyone can create an account and add to it. If its confusing, then an explanation that isnt so confusing can be made. No special access is required, just sign up for an account if you dont have one. Additionally the wiki documentation is used for a daily process that creates a pdf for offline reading. The pdf location is at http://www.0xdecafbad.com/files/fsdoc.pdf and is something I personally do for the community. Any formatting problems in the pdf should be reported to me, any problems in the content should be updated on the wiki and they will then be reflected in the pdf within 24 hours. The pdf is already over 480 pages, but its not complete, so help is requested to get that a little more finished.

Maybe add a new page called "Documentation requests" where user ask for some parts to be better documented.

at http://wiki.freeswitch.org/wiki/Documentation there is a documentation guideline section at the top, so that the pages can have a uniform look and feel, and at the bottom is a list of missing pages and empty pages. There are 40 such pages already that do need to be filled in at some point. Last but not least, instruct users on the firstpage of the wiki how they can

give documentation feedback (via any of the above options).

Being a wiki you are able to do that if you feel it needs to be done, you can create a new page which goes into that or if its small enough make a new section on the documentation page (which is linked to directly on the top left of every wiki page). -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!

On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:

Ahh.. My mistake. I searched for both "FAQ" and "Frequently asked questions" without getting a hit.

The searching on that site is admittedly a bit weak, I do not know what to do about that, nor do I have any control over that since its the people that have direct control of the site. I will talk to someone and see if there is anything they can do in that regard.

Then I saw this in the documentation guidelines: "Try to avoid FAQs". My conclusion was therefore that it was removed. But I found it now =)

The 'try to avoid faqs' in the guidelines refers to documenting a module or something else. If you were to document mod_something there shouldnt be a need for a FAQ about that module, since the documentation should explain what it does and how to use it. If you feel the need for a FAQ on mod_something then perhaps the documentation itself should be extended to answer those questions. :)

My point was that people who can't contribute with information should be able to REQUEST information. Those requests shouldn't be added in the documentation, but in the Talk pages or special request pages

I dont understand, they have to edit a wiki page to request information or add to the talk section, but they cant edit a different wiki page to actually create documentation? Almost seems like its an extra layer of stuff that people would have to actively seek out to read and then update the documentation just to create this process. Why cant people contribute to the documentation effort but could contribute to wiki pages on the same system?

I created the documentation guidelines page too :) But that's for ppl that can actually contribute in the documentation. Not for ppl that as missing or not understanding some documentation.

everyone can contribute, you make it sound like only some people are allowed and others cant. Maybe that is my misunderstanding when you constantly refer to people who cant edit documentation but can edit some other page on the wiki. I just dont understand why this extra layer is a good thing, if people can add to those pages they can add to the documentation itself. There is a list of missing documents, which I periodically update, as well as a list of empty pages which I update at the same time. If someone were to link to a page that doesnt exist, during the generation of the PDF I would see that and be able to edit that list, thus forming a 'weak spot in the documentation' list, which currently is there, on the main documentation page. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!

On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:

I'm not talking about if people can or can't edit the pages.

I'm talking about users that want to find or read documentation (not contribute). For instance: New users.

Ahh you kept saying people who 'cant' which led me to believe you were talking about people who cant as opposed to wont. If they wont add, why would they add to something else? So I am still confused why there needs to be a "second class" documenter. Those that request others do things for themselves that they wont. What I want is a way for those users to give us that feedback. They

can, as you say, edit the pages and add their questions / suggestions directly in the page. But what will a page look like if 20 users have added questions / suggestions for improvement on it?

when the improvements are done those questions wont be there. Its been done on other pages where people didnt understand something, and it seems to work well since that highlights the exact area that caused confusion. I think it works a bit better infact since I generally dont click on every link in a page just to see if anyone is using the talk pages or some tertiary page to see if anyone has requested something. A request for missing documentation can be made by linking to a non-existant page. That I do check since its part of the output of my pdf generation script.

There are a section on the first page called "Community and Support" on the first page which tells the user how to get help. Maybe there should also be a section called "How to give feedback" too?

feel free to add to that page, as you have said in the past you have created documentation so you do understand how to use the wiki system, and can do some of these things. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!

On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:

How can they add/improve documentation if they can't understand how things work? What they can do is to tell us what they don't understand or if they are missing something.

But how should they do that? And do they know that they can give us feedback?

You bring up the point I was trying to get to come out. How can they update a wiki page if htey dont understand the wiki system? Further if they do understand it, but dont understand the FreeSWITCH[tm] specific parts, how can they add/improve? Well that is easy, they can do what has been done over the last year, and say 'huh?' or even more verbose comments inline with the parts that dont make sense. There is another alternative, and that would be a mailing list, which can be used in addition, there can be an irc channel, which can also exist in parallel. There are a lot of options. I know perosnally I wont check a tertiary page for requests/comments because I do stuff on the wiki ninja style, just get in and get out. If I see something that isnt there (probably because I was looking for it) I add it. I am unsure how many people will semi-regularly check tertiary pages for comments either, given the fact that the 40 pages that are missing have been on the main documentation page for months I think that few who edit things do. There were a couple pages that others did, a few that I did, but most dont seem to look there for an easy list of what needs to be done. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!

On 9/20/07, Jon Radel <jon@radel.com> wrote:

Speaking just for myself, mind you, I find documentation written by those without knowledge, or without clue, or complete lack of writing skills, tends to be unenlightening. If someone who is trying to figure out what it all means, gathering knowledge and clue best he can, decides he has nothing to add yet other than questions (and he suspects that they're not even very clever questions quite yet), might he not feel just a little shy about "defacing" the documentation? Allow people to self-select out of editing the documentation while still participating.

That may be, but if you see a page like that, and figure it out do you go back and update the wiki? For anything that was missing and you eventually figured it out do you go back and update the wiki now that you know? Someone may feel shy about that, but to discourage all people from contributing just because they arent professional writers would seem to generate a lot less documentation than what is already done. Many of hte pages werent written all in one shot, they were started by someone, added to by someone else, refined by a 3rd person and so on. Thus is the nature of a wiki. Personally I would rather see people who dont have good writing skills at least try than people complain there isnt documentation, and demand help, and then refuse to document anything (that has happened before). For someone to say that something is unclear, odds are its unclear for others as well, and documenting they are unsure of something cant hurt as I see it. Perhaps someone who is reading that page to refresh their memory will see that comment and decide to clarify something. But then this is a community effort, you will always have some in the community that feel it should be done more of a closed documentation site to prevent crazy people from entering wrong information, you will have others that think there shouldnt even be passwords and accounts, and the majority will be somewhere in between. It will be impossible for everyone to agree all the time, especially when the project gets new members to the community. Choice and selection in how people interact with the documentation should be provided, one reason why I did hte pdf to give more choice in how you deal with it (the other is that the search tool works better :) The problem with that however is unless there is someone to read and act upon those requests then the requests are useless. If others are volunteering to actively monitor such requests and act upon those, more power to you. I know that personally I will not because I dont spend that much time on the wiki itself anymore. As a result I am suggesting methods that I would notice, as would anyone else acting like myself - just goto the page to refresh memory and leave. Anyone is free to create a page that would request people to add stuff there, and likely it would have taken less time than this thread has already consumed. I still believe the 'justification' comments about this suggest that it wont be used that often however, specifically: they dont think their question is clever they wont ask - why would they ask on a seperate page then? they dont know how to use the system - how can they use it then? they dont know enough to know what htey are looking for - they may just use that page as a trouble ticket system and so on. But anyone who wants to do it is more than welcome to, just click the edit link at the top of the page, create a link to the new page, save and click on that link to create the new page. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!