[Freeswitch-docs] Docs Team spreadsheet

Fri Jun 13 03:01:05 MSD 2014

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

-- 
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/20140613/ab390ff8/attachment-0001.html 