[Freeswitch-docs] Docs Team spreadsheet

Areski areski at gmail.com
Thu Jun 12 19:51:26 MSD 2014 

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
>> 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
>>
>
>
>
> --
> 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
>



-- 
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/20140612/05fad5aa/attachment-0001.html

Join us at ClueCon 2014 Aug 4-7, 2014
More information about the Freeswitch-docs mailing list