[Freeswitch-docs] Docs Team spreadsheet

Thu Jun 12 23:43:38 MSD 2014

The "Confluence Standards" page is my beginning to provide guidance to newcomers. Also, there is a good YouTube video at the bottom of that page that teaches you how to edit Confluence; it is about 1 hour long.

Even if people simply copy the old wiki pages to Confluence that is helpful, but then they must mark the pages "Moved" on your spreadsheet. Then we can go back and edit them for proper content as time permits.

Bote

From: Areski [mailto:areski at gmail.com] 
Sent: Wednesday, 11 June, 2014 18:57
To: Bote Man
Cc: Freeswitch-docs at lists.freeswitch.org
Subject: Re: Docs Team spreadsheet

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