[Freeswitch-docs] Docs Team spreadsheet

Mon Jun 16 09:45:01 MSD 2014

My guidelines for the Table of Contents macro include listing "About" in the "Exclude" field so that it will not be listed in the ToC.

Not every Confluence page has been edited to meet the new guidelines which is why you see pages that look like they have not been edited. The reason is that they have not been edited :-/

More hands make short work.

Bote

From: Areski [mailto:areski at gmail.com] 
Sent: Friday, 13 June, 2014 10:50
To: Bote Man
Cc: Freeswitch-docs at lists.freeswitch.org
Subject: Re: Docs Team spreadsheet

I totally agree with the need of About section and have good description in the header.

My problem is more on the layout aspect.

`About` is a Header (h1) and so appear it will appear in ToC, therefore in the order of the content `About` is behind when we display the ToC, and this bug me a bit... but I could live with it :)

On Fri, Jun 13, 2014 at 4:32 PM, Bote Man <bote_radio at botecomm.com> wrote:

I think it is important to have About always be the very first thing, and provide an accurate description of the page. Some pages remain a mystery by their title J

If the reader finds this interesting, then comes the table of contents to find section headings. If the page is short, a ToC seems unnecessary, but if you think it helps even on short pages then OK. I'm just trying to save work and be lazy.

Bote

From: Areski [mailto:areski at gmail.com] 
Sent: Friday, 13 June, 2014 07:37

To: Bote Man
Cc: Freeswitch-docs at lists.freeswitch.org
Subject: Re: Docs Team spreadsheet

2 little comments I hope we can discuss on the guideline:

1. I have the feeling that the layout will look better if the ToC is above the "About" mandatory title

2. Small page with few titles can still gain by having a ToC (without the expand), ie: https://confluence.freeswitch.org/display/FREESWITCH/mod_redis

    the ToC give you a quick view of how the page is organized.

On Fri, Jun 13, 2014 at 1:01 AM, Areski <areski at gmail.com> wrote:

Thanks for the feedback, I will be able to progress with what I got so far.

I dont have delete permission on pages, could you remove this one : https://confluence.freeswitch.org/display/FREESWITCH/Script+Languages

We will keep this one that was already created.

Confluence is really a huge step forward from the previous wiki. I played a bit with moving page, it's magic.

If there is a problem with the spreadsheet let me know, so far I haven't see anyone editing it!

On Thu, Jun 12, 2014 at 9:43 PM, Bote Man <bote_radio at botecomm.com> wrote:

A-HA! You have discovered the downfall of the wiki: it is too easy for people to create many pages without regard for what already exists. This is why we want to organize the Confluence wiki to make it easier to find things and create order out of chaos J

"I created this page:

https://confluence.freeswitch.org/display/FREESWITCH/Which+scripting+language+should+I+use

and the parent is "FreeSWITCH explained", now this page appear in the left menu. 

How can I avoid that ?"

Whenever you click the CREATE button at the top of Confluence, the new page becomes a child of the current page. So if you are currently viewing the top level page "FreeSWITCH Explained" the new page will be created under that and so will appear as a top-level outline heading.

I think it is best to change the title of that page (and pages like it) to a simple "Scripting" or "Script Languages", discuss the choices, then post pages specific to each script language as children of that page.

As a user, I prefer one long page on a topic as opposed to a bunch a smaller pages that I must hunt down to find. I can always hit Ctrl-F and search for text inside a long page to find it quickly. Using the search engine of the host site is always guess-work.

I also have been persuaded by smarter people that FAQ are evil. Instead of guessing the questions and trying to answer them, let's just explain the topic clearly and add or edit as questions arise on the mailing list and IRC channel. The documentation should always match the current Master version of code, the latest on offer.

I have confidence that you will handle the Lua pages well. I do not know Lua so if you do, then feel free to organize it the best way. I think it is nicer to have one page discussing, for example, Lua database handling instead of multiple pages, but if you think that would make the pages too complicated then go ahead and split them out. Certainly, combine the many old wiki pages the best way that you can find. 

Right after I copy a page from the old wiki to Confluence, I then make obvious edits like setting the proper heading levels. This is for both readability and to help screen readers interpret sections of the page for those with poor eye sight.

The good thing is that Confluence allows us to move pages at any time so if you find that a page must be moved, go to Reorder Pages, expand the tree, grab the page with your mouse, and drag it to the new location. Release the page on top of an existing page to move it to a child of that page, move it between existing pages to move it in between them at the same outline level.

Thanks!!

Bote

From: Areski [mailto:areski at gmail.com] 
Sent: Thursday, 12 June, 2014 11:51

To: Bote Man
Cc: Freeswitch-docs at lists.freeswitch.org
Subject: Re: Docs Team spreadsheet

Hi Bote & Co, 

I moved few pages today and got my hands comfortable with Confluence.

I created this page:

https://confluence.freeswitch.org/display/FREESWITCH/Which+scripting+language+should+I+use

and the parent is "FreeSWITCH explained", now this page appear in the left menu. 

How can I avoid that ?

I reformatted mod_lua page (a topic I know well), https://confluence.freeswitch.org/display/FREESWITCH/mod_lua

This page is very long,,, very long, plus there is 19 pages about Lua in total, which are quite disorganized.

Existing pages related to Lua

https://wiki.freeswitch.org/wiki/Mod_lua

https://wiki.freeswitch.org/wiki/Mod_lua/Example_dialplan

https://wiki.freeswitch.org/wiki/Mod_lua/Serving_Configuration

https://wiki.freeswitch.org/wiki/Mod_lua/Examples/Extra

https://wiki.freeswitch.org/wiki/Installing_LuaSQL

https://wiki.freeswitch.org/wiki/IVR

https://wiki.freeswitch.org/wiki/Lua_MythTV_alert_example

https://wiki.freeswitch.org/wiki/Fakecall_responder

https://wiki.freeswitch.org/wiki/Call_retry_based_on_hangup_cause

https://wiki.freeswitch.org/wiki/Bridging_two_calls_with_retry

https://wiki.freeswitch.org/wiki/Lua_Intercom

https://wiki.freeswitch.org/wiki/Lua_freeswitch_dbh

https://wiki.freeswitch.org/wiki/Lua_Welcome_IVR_Example

https://wiki.freeswitch.org/wiki/Examples_db_agent_login_lua

https://wiki.freeswitch.org/wiki/Make_API_calls_directly_from_Lua_code

https://wiki.freeswitch.org/wiki/Examples_directory_lua_asr_tts

https://wiki.freeswitch.org/wiki/Examples_directory_lua

https://wiki.freeswitch.org/wiki/Lua_Examples

https://wiki.freeswitch.org/wiki/Category:Lua

I would like to propose a new structure on Confluence:

First split and change the mod_lua page.

0) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua

    -> Remove API & FAQ (they will have their own pages)

    -> Point to API, Serving Configuration, Lua with Database, FAQ, Examples

The rest of the pages will be child pages under Mod_lua:

1) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/API

2) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Serving_Configuration

3) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Database

    -> this page will list the child pages

    3.1) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Database/DBH

    3.2) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Database/LuaSQL

4) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/FAQ

5) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples

    -> this page will list the child pages

    5.1) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/

    5.2) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Dialplan

    5.3) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/IVR

           -> Previous IVR page (https://wiki.freeswitch.org/wiki/IVR) merged with Lua_Welcome_IVR_Example

    5.4) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra

            -> this page will list the child pages

    5.5) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/Bridging_two_calls_with_retry

    5.6) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/Fakecall_Responder

    5.7) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/MythTV_alert

    5.8) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/Intercom

    5.9) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/Agent_login

    5.10) https://confluence.freeswitch.org/display/FREESWITCH/mod_lua/Examples/Extra/Directory

            -> merge Examples_directory_lua_asr_tts and Examples_directory_lua

Note: 

Those 3 pages will be deleted:

- https://wiki.freeswitch.org/wiki/Lua_Examples

- https://wiki.freeswitch.org/wiki/Category:Lua

- https://wiki.freeswitch.org/wiki/Call_retry_based_on_hangup_cause

   -> This page will be deleted but the example reused inside the mod_lua/API page

Extra:

On a 2nd phase, we should put some effort in rewriting some part of mod_lua pages

-> Reorder the topics that need to be covered by priority

-> Ensure that examples are simple enough and point to more complex ones

I would appreciate comments / thoughts?

On Thu, Jun 12, 2014 at 12:56 AM, Areski <areski at gmail.com> wrote:

> But this documentation project is like a Navy ship: if you see a job that you can do, then do it! J

I would agree, but there is certainly peoples willing to help which needs clear instruction of what they can do. 

If we don't see clearly what is remaining, there is a risk of being discouraged.

On an extra note: 

After scrapying the actual Wiki, I had a bunch of data about the pages, I thought it could be fun to try to display all the wiki page-relations on a graph to see what the big monster have in his stomach (a very weird idea)

http://dl.dropboxusercontent.com/u/6076501/d3-wiki/index_all.html

It's a huge canvas so you need to zoom out in order to see something, well it's a bit pointless it's just too much data to see anything.

I was hoping it will show how the wiki is actually organized, but apart from seeing the leaf-pages, this doesn't have much value :/

The dataset here if someone is interested: https://dl.dropboxusercontent.com/u/6076501/d3-wiki/wikidataset.json

On Wed, Jun 11, 2014 at 7:03 PM, Bote Man <bote_radio at botecomm.com> wrote:

I don't know. Perhaps the "Edited by" field should only show the last person who worked on the page? But this requires manual entry and it's easy to forget to add that information to the spreadsheet.

I assume that if somebody marks the page "Complete" then that person's name should appear.

But this documentation project is like a Navy ship: if you see a job that you can do, then do it! J

Bote

From: Areski [mailto:areski at gmail.com] 
Sent: Wednesday, 11 June, 2014 10:49

To: Bote Man
Cc: Freeswitch-docs at lists.freeswitch.org
Subject: Re: Docs Team spreadsheet

Hi John,

I'm tempted to add `reviewed by` column next to `assigned`, 

so that each completed page got also an extra person to review it. 

Thoughts ? will it be too much work?

The spreadsheet is down to 1437 pages, my scrapying techniques generated duplicate.

https://docs.google.com/spreadsheets/d/1qsG-kRymvKlNBapnBLw86W130VdbnK6naYapbR_UNds/edit#gid=1187898333

It's also a bit cleaner now.

On Wed, Jun 11, 2014 at 12:41 PM, Areski <areski at gmail.com> wrote:

Hi John,

Thanks for the inputs.

There is some advantages in using a bug tracker for controlling the doc conversion, especially if we want to do a bit more than just copying pages,

I understand we need to be pragmatic, so I would agree on using a spreadsheet for now and maybe at later stage consider an issue-tracker, there is plenty tools out there that could allow us to have enough customization for what we need.

> !!==>>  Just now I edited a field without being logged in, so anybody can edit that spreadsheet right now!!

Not the case anymore, I removed public edition of the spreadsheet and added the edit permission only for the peoples I know are working on this. Any of you can now add extra editors to this document, this is something we need to do on request.

I added 2 extra status:

  1) Pending - means the page has not been looked at yet (all pages are marked as pending now)

      This will have some advantages if we want to filter the pending tasks on an other sheets or document.

  2) Delete - means the page doesn't need to be converted, ie this page for example (http://wiki.freeswitch.org/wiki/Help:Contents)

> But remember: pages still must be edited as changes are made to FS code that must be documented.

I suppose we can try sooner to push good practice here, and invite peoples in opening Jira docs ticket for new pages that have content not up to date, which require good experienced fs-dev to look at it.

On Wed, Jun 11, 2014 at 3:39 AM, Bote Man <bote_radio at botecomm.com> wrote:

Upon further review: the Jira system does not seem well-suited to documentation tracking. I clicked Create and the details like CPU and operating system just get in the way, plus it does NOT have the fields and statuses that you mentioned.

So I'm inclined to go with your spreadsheet. You have already done the work and it's already online and editable (hopefully only to members of the Docs Team!) so let's use that. 

!!==>>  Just now I edited a field without being logged in, so anybody can edit that spreadsheet right now!!

I made the Status field a list of choices so that it remains consistent throughout the table. I made Editing, Moved, and Complete. If it's blank it means the page has not been touched yet. If you accidentally enter a status, hit DELETE to erase that entry. This keeps the choices simple.

Moved - means the page has simply been copied from the old wiki to Confluence, but still needs to be formatted according to the guidelines.

Editing - means somebody is in the process of formatting and editing the page to ensure that the content describes the current Master code of FreeSWITCH.

Complete - means the page is up to date.

But remember: pages still must be edited as changes are made to FS code that must be documented.

Thanks!!

John Boteler

Bote Communications

Fort Lauderdale, FL

From: Areski [mailto:areski at gmail.com] 
Sent: Tuesday, 10 June, 2014 12:30
To: Brian West
Cc: Nguyễn Văn Nghĩa Em; Bote Man; Mario G; Ken Rice; William King; ycamargo at xmartek.com
Subject: Re: FS Docs: wiki to Confluence move

Hi Bote Man!

I did a scrapping of the wiki and created a spreadsheet here, the spreadsheet is editable:

https://docs.google.com/spreadsheets/d/1qsG-kRymvKlNBapnBLw86W130VdbnK6naYapbR_UNds/edit#gid=1187898333

maybe this can be of some use? we could for instance start to work on a spreadsheet or use the spreadsheet (csv) to create tasks in bug tracker.

* (there is 2858 pages in total)

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355 <tel:%2B34650784355> 
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-- 
Kind regards,
/Areski

----
Arezqui Belaid, <areski at gmail.com>
Founder at Star2Billing (www.star2billing.com)

Tel: +34650784355
Twitter: http://twitter.com/areskib 
LinkedIn: http://www.linkedin.com/in/areski 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-docs/attachments/20140616/21c53084/attachment-0001.html 