[Freeswitch-docs] Docs Team spreadsheet

[Areski]

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



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