[Freeswitch-docs] Documentation Jira, guidelines

Wed Jun 11 04:56:27 MSD 2014

[ I'm moving this to the mailing list. The entire documentation team should be on the mailing list for these discussions, so please let BKW know if you are not on the list. Thanks. ]

Welcome back to life!

A) I think the Confluence permission matrix might still need some work. Ben Langfeld could not do anything the other day while logged in, he had to log out and post as anonymous in the blog comments at the bottom of the page for me to apply.

B) BKW created a Jira for the Documentation project at

https://jira.freeswitch.org/browse/DOCS

Now, unlike a software project I considered the documentation to be self-documenting J For example, if a page is not formatted properly it is apparent to the eye.

But with many people helping to move the wiki pages over perhaps we should use Jira to track the state of each Confluence page. I just want to avoid creating yet another database to maintain if it will not move the project forward. If it helps, then let's use it. 

Suggestions?

C) That's quite a spreadsheet! I note a block of pages that are the FS Weekly which will not appear in Confluence. Also many pages for each channel variable. I think 2000+ pages is wayyyyyyyyyyyyyyyy too much, especially when many of the variable pages in old wiki consist of the basic template that was never filled out.

Our objective is to make Confluence clean and concise, so if we can combine many small wiki pages into one useful Confluence page, that is a good goal. 

D) All pages need reformatting on Confluence I'm finding. Please follow the guidelines on

https://confluence.freeswitch.org/display/FREESWITCH/Confluence+Wiki+Standards+and+Guidelines

>From your questions:

1) Some pages have been moved, but not tagged on the old wiki, this is true. Originally I put the wiki {{warning}} at the top with a pointer to the Confluence wiki, but later we chose the Category:Moved tag since it allows a list of moved pages to be created automatically on the old wiki.

2) There are many pages that should not be moved, I think.

3) There are some pages that were moved to Confluence at the beginning that do not follow the guidelines because we had not developed them yet, plus we did not know all the capabilities of Confluence. If anybody sees a page that needs attention, please correct it.

4) Special wiki pages can not be used, correct. Confluence has those built-in.

5) Confluence has many macros that are similar to the wiki special pages and template functions. This includes a Child Pages macro as seen on

https://confluence.freeswitch.org/display/FREESWITCH/Modules

The Confluence wiki is still a work in progress so we are keeping things "loose" while we discover the best practices to use.

If anybody finds a better way to do something, please tell us on this mailing list so we all can benefit from it.

Thanks!

Bote

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!

Sorry to come back to live so late. I certainly missed everything that has been discussed on the topics, 

but if you still need help on moving documentation let me know, Ken just sorted my confluence access 

so I m ready to get started.

My comments on few things, sorry in advance if some points sounds stupid or have been discussed already.

What do you think if we put some tracking of the work in place, something like this:

A) Define a list of all pages that need to be moved on Spreadsheet 
B) Push all `validated pages` to a bug tracker (maybe Jira)
C) Define a workflow, ie: 
           - Waiting (need to be moved), 
           - Need content review 
           - Review for Deletion (page we think we may want to delete)
           - Need reformatting (some page has been moved but the formatting is bad so we need to come back to them at some stage)

           - Need a menu
           - Solved
D) Then let the folks picking the tasks they want

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)

Few things I noted and on which I would appreciate some lights:

1) I see some pages that has been moved but not tagged on Secret-Wiki, ie  <https://70.169.193.216/wiki/Installation_for_Windows> https://70.169.193.216/wiki/Installation_for_Windows - tag with "category:moved"

Any special reasons why the tag is missing?

2) There is page we might not be willing to move, ie  <https://70.169.193.216/wiki/Make_test> https://70.169.193.216/wiki/Make_test (maybe we can mark them on a bug tracker for review, waiting for deletion until a BDFL come along and take a decision)

3) This page doesn't use the menu correctly :  <https://confluence.freeswitch.org/display/FREESWITCH/Configuring+FreeSWITCH> https://confluence.freeswitch.org/display/FREESWITCH/Configuring+FreeSWITCH

    We may want to try to use Table content correctly everywhere ( <https://confluence.atlassian.com/display/DOC/Table+of+Contents+Macro> https://confluence.atlassian.com/display/DOC/Table+of+Contents+Macro), there is no many pages where we do so, ie  <https://confluence.freeswitch.org/display/FREESWITCH/Installation> https://confluence.freeswitch.org/display/FREESWITCH/Installation

4) I suppose the User page, Special pages and Talk pages don't need to be moved  <http://wiki.freeswitch.org/wiki/User:Vmelachervu> http://wiki.freeswitch.org/wiki/User:Vmelachervu

5) Child pages mechanism seems something we may want to consider, see it here in action:  <https://wiki.asterisk.org/wiki/display/AST/Asterisk+Command+Reference> https://wiki.asterisk.org/wiki/display/AST/Asterisk+Command+Reference

     Maybe something to consider?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-docs/attachments/20140610/1e415f00/attachment-0001.html 