PMC Documentation Meeting 20100219
Date: 2010-02-19
Time: 11AM GMT
Venue: irc #adempiere-team
Support Spreadsheet: Adempiere PMC Documentation
Chat times in GMT-5
(06:02:31) red1 [~red1@202.126.50.60.klj04-home.tm.net.my] entered the channel.
(06:02:50) red1: halo, hola everyone
(06:02:53) CarlosRuiz: hi red1, we just finished our architectural meeting
(06:02:57) viola: hi
(06:03:01) red1: darn :>
(06:03:03) CarlosRuiz: just in time to start our documentation meeting
(06:03:08) red1: miss the big boys stuff
(06:03:27) red1: ok.. i am ready
(06:03:41) viola: ok bye all!
(06:03:54) CarlosRuiz: bye Jörg
(06:04:05) viola has left the channel.
(06:04:33) CarlosRuiz: ok red1, can I propose the agenda?
(06:05:27) red1: sure
(06:05:44) red1: so there is only trifon besides us?
(06:06:30) trifon: :)
(06:06:41) CarlosRuiz: it seems Bayu is not there
(06:06:58) CarlosRuiz: ok, proposed agenda
(06:06:58) CarlosRuiz: - define a periodic meeting
(06:06:58) CarlosRuiz: - review the scope defined in PMC Structure
(06:06:58) CarlosRuiz: - review a potential list of initial tasks to work on, i.e. wiki guidelines, construction of a FAQ
(06:07:00) red1: maybe he was not aware or miss the time
(06:07:50) CarlosRuiz: do you want to add something else to the agenda?
(06:08:15) red1: sort of ok.. i like to raise certain issues.. and they can be done in the agenda
(06:08:34) CarlosRuiz: ok / first item then
(06:08:43) red1: i am thinking of the important issue of purpose and importance of documentation as for end users
(06:09:06) CarlosRuiz: can we try a periodic meeting - maybe biweekly? which weekday and time will be ok?
(06:09:07) red1: i mean that documentation is not for just transparency sake but for product and business sake (what many are screaming about)
(06:09:43) red1: i think monthly is more appropriate for concurrent chat.. and we use wiki for asynch chat
(06:09:57) red1: there should be a documentation team page for offline meet
(06:10:29) CarlosRuiz: ok - monthly is ok for me - which day is ok?
(06:10:52) red1: this day seems ok.. a saturday
(06:11:23) bcahya [~Bayu@202.70.58.158] entered the channel.
(06:11:42) CarlosRuiz: Hi Bayu
(06:11:54) bcahya: hello Carlos
(06:12:12) bcahya: good day Trifon, Red1
(06:12:15) CarlosRuiz: we're initially trying to set up a periodic meeting
(06:12:21) red1: i wish to forward a topic i m not sure which agenda it can go into.. its about Standards of Documentation
(06:12:21) CarlosRuiz: redhuan propose monthly
(06:12:42) bcahya: yes, no problem
(06:12:56) red1: or arrangement of documentation.. as there are lots of it and its an issue of that
(06:13:29) CarlosRuiz: the scope here (to review)
(06:13:29) CarlosRuiz: http://www.adempiere.com/index.php/PMC_Structure#Functional_Documentation
(06:13:29) CarlosRuiz: is
(06:13:29) CarlosRuiz: "This group is in charge of defining guidelines to write functional documentation, writing and maintaining it."
(06:13:32) red1: i think it can be on your 4th agenda item... list of initial tasks
(06:14:05) CarlosRuiz: my thinking is that first important task is to define guidelines for the wiki organization
(06:14:31) CarlosRuiz: and once defined / others can join in the effort of organizing the wiki and creating new content
(06:14:58) CarlosRuiz: do you share that?
(06:15:14) red1: yes that is right
(06:15:18) red1: and can solve what i raised
(06:15:36) CarlosRuiz: with that in mind - do you think a monthly meeting is ok?
(06:15:41) red1: but i see more of filtering and reorganising content .. not having more :)
(06:15:54) red1: i think continous communication is needed in a specific page or forum
(06:16:01) bcahya: since I have a little experience with wiki, then I am following the best practice
(06:16:08) red1: since we have a Content and Documentationg i think sub forum
(06:16:48) CarlosRuiz: or we can think in collecting and organizing documentation in a different CMS / but I'm comfortable with wiki
(06:17:07) red1: i am impressed by what CarlosRuiz did with Functional Manual.. and i think that should be the basis or tree of all technical doc
(06:17:15) red1: and others should be deprecated
(06:17:23) red1: or realigned to it
(06:17:41) bcahya: yes, I think wiki is the way to create our documentation
(06:18:28) CarlosRuiz: I guess we can write some guidelines about:
(06:18:28) CarlosRuiz: - how to write a HowTo
(06:18:28) CarlosRuiz: - how to organize the FAQ and how to maintain it
(06:18:28) CarlosRuiz: - how to add content to the manual pages
(06:19:04) CarlosRuiz: wiki is pretty disorganized at this moment- I think it's very complete, but hard to find, because it's not standarized neither properly indexed
(06:19:53) red1: agreed
(06:20:38) red1: i think less is better
(06:20:46) red1: wonder if Howto is necessary since FAQ is there
(06:20:51) CarlosRuiz: back to the monthly meeting - this sound ok for you two?
(06:20:51) CarlosRuiz: third friday each mont, 11GMT
(06:20:51) CarlosRuiz: purpose of the meeting to review the tasks done, and to propose new tasks
(06:21:31) CarlosRuiz: 1h duration
(06:21:43) CarlosRuiz: is that ok red1 and bcahya?
(06:21:45) bcahya: thats fine
(06:21:46) red1: i agree with that
(06:22:50) CarlosRuiz: ... one minute / setting up calendar
(06:23:20) red1: trifon: ?
(06:23:37) CarlosRuiz: ready - invitation sent
(06:24:01) CarlosRuiz: trifon, do you want to be part of documentation group of PMC?
(06:24:08) trifon: No.
(06:24:22) trifon: sorry i do not have intersti in the doc.
(06:24:29) CarlosRuiz: :-) so, we have an spy on the meeting :-D
(06:24:35) CarlosRuiz: ;-) just joking
(06:24:45) trifon: constant spy.
(06:24:49) trifon: not only spy :)
(06:25:11) bcahya: :)
(06:25:48) CarlosRuiz: red1 - I see a lot of HowTos there
(06:26:07) red1: wonder if they can be converted to FAQs
(06:26:08) CarlosRuiz: but every one with a different format - not linking to the manual pages for screenshots for example
(06:26:20) red1: frequently asked questions theme
(06:26:34) CarlosRuiz: not sure - I think a HowTo is to guide a process
(06:26:38) red1: and again, wonder if we can link them or fit them to the functional manual
(06:26:43) red1: then we got only ONE master link
(06:26:57) red1: yes but i rather there be less to show on front page
(06:27:02) red1: its too messy
(06:27:06) CarlosRuiz: FAQ has a different target than HowTos than Manual pages
(06:27:19) red1: FAQs ; Manual .. thats it!
(06:27:27) red1: feels free
(06:27:30) red1: not choked
(06:27:47) red1: FAQ 1: how to setup? ... etc
(06:27:59) red1: FAQ 1.1 how to setup on Mac OS
(06:28:15) red1: just my preference.. i am open to other ways
(06:28:39) red1: your Reference Manual (sorry i wrongly said Functional before)
(06:28:49) red1: .. is a good starter
(06:29:01) red1: FAQs, .. Reference .. thats it!
(06:29:27) red1: newbies go to FAQs... experts or those ok.. go to Reference
(06:29:41) red1: then we think about the type of audience..
(06:29:43) CarlosRuiz: let's check:
(06:29:43) CarlosRuiz: FAQ is where newbies find answers to their first questions
(06:29:43) CarlosRuiz: and oldies remember them :-)
(06:29:43) CarlosRuiz: Reference Manual -> is a complete description of screen, fields, and it allows to add contributions to describe the process, or to annotate things
(06:29:43) CarlosRuiz: HowTo -> describe a process (probably composed by several manual pages), step by step
(06:29:53) red1: technical, functional, sales... end-users
(06:30:26) red1: Howto seems fine but should be sub-linkages
(06:30:32) red1: under FAQs and Reference
(06:30:47) CarlosRuiz: yep
(06:31:00) red1: i.e. in an FAQ.. i.e. How To Setup.. (link to Howtos)
(06:31:11) red1: even marketing material
(06:31:24) red1: FAQ.. is there marketing material? .. (link to ..)
(06:31:33) red1: FAQ is natural language of asking
(06:31:56) red1: and we dont want those idiots to bother us repetitively
(06:32:04) CarlosRuiz: and FAQ must have subsections
(06:32:04) CarlosRuiz: installation faq
(06:32:04) CarlosRuiz: accounting faq
(06:32:04) CarlosRuiz: ...
(06:32:10) red1: so we reply, "have u read the FAQs?"
(06:32:20) red1: agreed
(06:32:36) red1: and FAQ as main heading gives a friendly welcome scene
(06:33:02) CarlosRuiz: sure - and avoid a lot of forum questions
(06:34:43) CarlosRuiz: so, I would propose as initial task to create two wiki pages:
(06:34:43) CarlosRuiz: FAQ_Guideline
(06:34:43) CarlosRuiz: HowTo_Guideline
(06:34:43) CarlosRuiz: ReferenceManualContribution_Guideline
(06:34:43) CarlosRuiz: and try to define there how they must be written and filled
(06:34:49) CarlosRuiz: sorry, three wiki pages
(06:35:04) CarlosRuiz: do you think any functional documentation can fall in these three categories?
(06:35:37) CarlosRuiz: and we create a HowToIndex
(06:35:37) CarlosRuiz: and maybe a ReferenceContribution index can be useful too
(06:35:43) CarlosRuiz: WDYT?
(06:35:50) red1: i think ALL documentation falls into just two links
(06:35:53) red1: i mentioned
(06:36:05) red1: but u re mentioning guidelines...
(06:36:15) red1: i suggest those to be under another FAQ
(06:36:31) red1: FAQ - what are the guidelines for project documentation?
(06:36:49) red1: under a master FAQ - How is the ADempiere Project organised?
(06:36:52) red1: :)
(06:36:59) CarlosRuiz: sounds good
(06:37:05) red1: i can put the history page under somewhere there
(06:37:18) red1: and readers are not overwhelmed
(06:37:26) red1: and we can produce a FAQ book in the end!
(06:38:56) CarlosRuiz: ok - I would like to collect these ideas as tasks in a google spreadsheet, is that ok?
(06:39:05) red1: more than ok!
(06:39:10) red1: i like the google docs usage
(06:39:13) red1: beats MS
(06:39:22) red1: and everyone can look at it
(06:39:42) red1: it can be a recommended practice for our project
(06:39:56) CarlosRuiz: ... setting it up ...
(06:40:47) CarlosRuiz: ready - invitation sent
(06:41:27) CarlosRuiz: can you please open the spreadsheet?
(06:43:05) red1: checking
(06:46:49) red1: still not in
(06:47:02) red1: oh.. i shuld check gmail
(06:48:39) red1: ok i am in
(06:48:43) CarlosRuiz: ok , I have defined 7 tasks there
(06:48:48) red1: yes i can see them
(06:48:52) CarlosRuiz: bcahya: did you receive the invitation for the spreadsheet?
(06:49:45) CarlosRuiz: is that ok, red1?
(06:49:45) CarlosRuiz: first month we can work on evolving the guideline pages - asynchronously - editing a wiki page, and discussing it in pmc maillist if needed
(06:49:46) bcahya: yes
(06:49:48) red1: also i like to suggest that documenting happens rather adhoc and will continue to be so.. we are just having a process of rearranging and not stopping them
(06:50:11) red1: i think one pre-task for us is the welcome statement on that
(06:50:26) red1: FAQ - How do i contribute documentation?
(06:50:47) red1: for example in our coding practice .. ppl do it in their branches first and undergo peer review
(06:50:53) red1: so can it be for doc writing
(06:50:57) red1: under their own pages
(06:51:10) red1: or even personal blogs
(06:51:16) CarlosRuiz: yes / but to avoid keeping the mess we need some sort of editors to drop or merge duplicated content / and to apply the guidelines to the new pages
(06:51:40) red1: yes i think that is for sure
(06:51:41) CarlosRuiz: good idea
(06:51:47) CarlosRuiz: we can open a branch in wiki :-)
(06:52:04) red1: i dont think it can be formal
(06:52:12) red1: it has to be allow adhoc writing
(06:52:16) red1: which is happening now naturally
(06:52:30) red1: our organising it is just a next step
(06:52:39) red1: not even evolutionary
(06:52:51) CarlosRuiz: yes - I mean - we can open a wiki space called Functional
(06:52:56) red1: it will keep adding some mess to things.. then we come in to sweep
(06:52:58) CarlosRuiz: like a QA process
(06:53:04) red1: more get the idea.. more will assist
(06:53:06) CarlosRuiz: people write and open new pages ad-hoc as today
(06:53:19) CarlosRuiz: and we pass them to functional after some QA
(06:53:21) red1: and i myself read them and then decide what to do..
(06:53:26) red1: mostly we categorize
(06:53:53) red1: and we have to wait for things to grow.. before we can trim
(06:54:16) CarlosRuiz: yes, instead of trimming, we apply some sort of QA and pass it to Functional with guidelines applied
(06:54:22) red1: of course now we are trimming .. so your proposal is correct
(06:54:28) CarlosRuiz: there are outdated content - and even wrong content
(06:54:36) red1: agreed
(06:54:55) red1: and those rejected can be archived
(06:55:33) red1: ok last 5 mins... what can we sum up? :D
(06:55:42) CarlosRuiz: yes / they don't need to be deleted, it can be commented on talk page
(06:55:51) CarlosRuiz: yes - time to go
(06:56:00) CarlosRuiz: so, we'll have a monthly periodic meeting
(06:56:14) CarlosRuiz: to review advance of tasks / and propose new tasks / and whatever related to documentation
(06:56:23) red1: we should have invited our webmistress in here ! :>
(06:56:25) CarlosRuiz: and we created a list of 8 initial tasks to work on during this month
(06:56:49) CarlosRuiz: sure red1 - can you invite her to be part of PMC documentation team?
(06:56:56) red1: sure i am locating her now
(06:57:07) red1: she is not online
(06:57:09) CarlosRuiz: ok - so we can finish the meeting - right?
(06:57:21) red1: can u send her your emails? and invite to the worksheet?
(06:57:26) CarlosRuiz: sure - you can invite her to become pmc member
(06:57:33) red1: of course we publish this chat log too
(06:57:37) CarlosRuiz: yep
(06:58:04) red1: her email is Jireh Arciaga <no_spam>
(06:58:15) CarlosRuiz: red1 - can you invite her?
(06:58:16) red1: i will write her then
(06:58:20) CarlosRuiz: gr8
(06:58:20) red1: sure i will do that
(06:58:42) CarlosRuiz: ok guys - thanks for attending
(06:58:53) CarlosRuiz: I have release meeting next
(07:00:59) red1: done!
