ofbiz-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Re: Onboarding strategy for Newcomers
Date Sun, 10 Aug 2014 17:21:25 GMT
The point of my document was to present an approach to organizing the 
documentation in a way that reflects the different phases of adoption.
I am happy that you identified some of the existing documents.

Are there any suggestions for improving or correcting my breakdown.

There is also the need for documentation that is required by new 
developers and it might be helpful to have some of the senior 
contributors take a few minutes to identify a roadmap that a person 
wanting to join the development team should follow.
What are the key documents (Architecture, schema docs, framework docs) 
that a new person should read before they read any code?
What are the key documents that someone should read before submitting a 
JIRA? before attempting a patch? before creating a new feature? (if that 
is the right hierarchy).

What documents are currently out of date and need to be updated?
What internal documents should be retired?

What documents should be reorganized to make them easier to maintain - 
for example, separate concepts from version specific info to reduce the 
scope and size of the documents that need regular updating?

Ron


On 10/08/2014 6:18 AM, Jacques Le Roux wrote:
>
> Le 10/08/2014 06:05, Ron Wheeler a écrit :
>> On 09/08/2014 7:11 AM, Jacques Le Roux wrote:
>>>
>>> Le 08/08/2014 17:49, Ron Wheeler a écrit :
>>>> The documentation issues discussed in the paper are certainly a 
>>>> barrier that can be addressed in OfBiz.
>>>> The paper is a little bit focused on building the PMS and internal 
>>>> OSS project community rather than worrying about adoption by users.
>>>>
>>>
>>> What is PMS? You mean PMC?
>> Yes
>>>
>>>>
>>>> As a potential user, I am going at the documentation problem from a 
>>>> bit of a different POV.
>>>>
>>>> If we look at the adoption process, we can identify several stages 
>>>> that an organization goes through during the implementation.
>>>>
>>>> In reading this, bear in mind that I have never done an 
>>>> implementation and am still at stage 1 of the OfBiz implementation 
>>>> process.
>>>> However I have been through this process a number of times over the 
>>>> last 40 years with roles ranging from the most junior programmer on 
>>>> the team to Technical Support manger to lead architect to the 
>>>> consultant preparing the RFP and the recommendation to management.
>>>> I expect that I have missed many things but I wanted to at least 
>>>> start a discussion about this potential way to look at the 
>>>> documentation.
>>>> I have tried to be a definite as possible about what I think is 
>>>> required so that people could take issue with my suggestions in a 
>>>> concrete way.
>>>> Please feel free to add, delete or modify  this.
>>>>
>>>> I would also ask that people who have contributed documentation 
>>>> take a few seconds to consider the various stages where you think 
>>>> the information contained therein is most helpful.
>>>>
>>>>
>>>> 1) Selection.
>>>> At this stage the new organization is looking at various 
>>>> alternatives from Quickbooks to SAP.
>>>> Key stakeholders - Accountants, business managers, IT, CFO, 
>>>> Marketing if the organization is looking at reselling or providing 
>>>> services based on OfBiz.
>>>> Important information:
>>>> - Feature descriptions and customization possibilities
>>>
>>> Feature descriptions :
>>> we have something up to 2004 
>>> https://web.archive.org/web/20100414073023/http://ofbiz.apache.org/feature-list.html
>>> which could be updated based on 
>>> https://cwiki.apache.org/confluence/display/OFBIZ/Main+New+Features
>>> An effort has already been made 
>>> https://cwiki.apache.org/confluence/display/OFBIZ/Feature+summary to 
>>> summarize this page but it's incomplete
>>>
>>> customization possibilities:
>>> we have 
>>> https://cwiki.apache.org/confluence/display/OFBIZ/Addressing+Custom+Requirements+In+OFBiz
>>> And soon the http://www.ofbiz-fr.org/ will make a proposition based 
>>> on https://code.google.com/a/apache-extras.org/p/ofbiz-adm/ (now 
>>> deprecated) which is related with 
>>> http://community.ofbizextra.org/community/control/COMMUNITY_HOME
>>>
>>>> - Organization profiles
>>>
>>> Could you elaborate?
>> It would be nice to have some articles explaining how organizations 
>> have benefited from adopting OfBiz.
>
> We have this 
> https://cwiki.apache.org/confluence/display/OFBIZ/Apache+OFBiz+User+List 
> and especially this 
> https://cwiki.apache.org/confluence/display/OFBIZ/Apache+OFBiz+User+Stories
>
>>>
>>>> - User interface and user documentation/ on-line help
>>>
>>> We have an online help in 2 forms, the ? button and 
>>> demo-trunk-ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
>>> There was also an effort 
>>> https://issues.apache.org/jira/browse/OFBIZ-4941 by the late Tom 
>>> Burn which is now in the branch 
>>> https://svn.apache.org/repos/asf/ofbiz/branches/webhelp-2012-12-07 
>>> from which an addon has been created by the Noegia team
>>
>>>
>>>> - Operational options - SaaS through a reliable supplier, BTF
>>> SaaS: we have multi-tenant 
>>> https://cwiki.apache.org/confluence/display/OFBIZ/Multitenancy+support 
>>> only scale by adding DBs though... So limited to small to medium 
>>> numbers
>>> What does BTF means?
>> Behind the firewall - installation on the organizations own hardware.
>>>
>>>> - TCO for SaaS and BTF
>>> TBD...
>>>> - Standards
>>> https://cwiki.apache.org/confluence/display/OFBIZ/Open+Source+Projects+and+Standards

>>>
>>> https://cwiki.apache.org/confluence/display/OFBADMIN/Best+Practices+Guide 
>>>
>>>
>>
>>>> - Support and technical documentation
>>> http://ofbiz.apache.org/documentation.html
>>>> - Feasibility - will it run in the IT infrastructure, can IT 
>>>> support it
>>>
>>> Yes they can. If they want to use an external app server there is 
>>> with 
>>> https://cwiki.apache.org/confluence/display/OFBTECH/Run+OFBiz+under+outside+Application+Servers

>>> though we are a bit late on this :/
>>>
>>>> - Stability and operational reliability
>>>
>>> I think we are good :)
>>>
>> Is there a doc describing the features/architecture/release 
>> process/bugs/etc.  from the point of view of stability and reliability
>
> I don't think we have something like that. It's not even clear to me 
> what you look for. Though not from a stability and reliability POV, We 
> have doc for
> features (see above).
> Nothing for architecture, though I saw dozens in projects but nothing 
> was ever contributed
> For the release process we have 
> https://cwiki.apache.org/confluence/display/OFBADMIN/Release+Plan
>
> Jacques
>
>>>>
>>>> Demo should be available that looks attractive and easy to use.
>>>
>>> I think we have something good, I mean from http://ofbiz.apache.org/
>>>
>>>> Video demos of common user functions could be a positive factor
>>>
>>> We have some not bad too 
>>> https://cwiki.apache.org/confluence/display/OFBTECH/Framework+Introduction+Videos+and+Diagrams

>>> maybe a bit old, but still relevant
>>
>>>
>>>>
>>>> The goal is to get through this stage as the winner!
>>>> If this part fails, the rest is pointless.
>>>>
>>>> 2) Demo
>>>> At this stage the organization needs to see if the thing actually 
>>>> works as advertised.
>>>> SaaS:
>>>> Supplier demo site with the organizations logo showing functions 
>>>> available in the SaaS version - Not an Apache problem but perhaps 
>>>> of concern to some who are offering OfBiz as SaaS
>>>
>>> We have some examples, we could link them from the multitenancy page...
>>>
>>> OK, I ran out of time, to be completed later...
>>>
>>> Jacques
>>> PS: some cleaning should be done in the FAQ page 
>>> https://cwiki.apache.org/confluence/display/OFBIZ/FAQ+-+Tips+-+Tricks+-+Cookbook+-+HowTo
>>> Hope I will get some time... one day...
>>>
>>>> BTF:
>>>> Stakeholders: IT Operations, Business Managers, System Analysts
>>>>
>>>> Important information
>>>> - Installation documentation
>>>> - User documentation
>>>> - Feature Checklist
>>>> - Video end-user Training
>>>> - Architecture Overview
>>>> - Customization Overview
>>>> - Implementation plan/checklist
>>>>
>>>> 3) Implementation Planning
>>>> In this stage, the development team may hire a consultant or sign a 
>>>> TSA to support the internal team or they may go it alone if they 
>>>> have the right staff.
>>>> The major task is to develop a requirements doc, a plan and a 
>>>> budget to get the system operational.
>>>> At the end of this step
>>>> - the CFO should be able to give a Go/NoGo for the budget
>>>> - the Business managers should be able to sign of on the functional 
>>>> requirements
>>>> - IT Operations should be able to sign off on the Performance, 
>>>> Security and DR capabilities
>>>>
>>>> Stakeholders: IT operations, System Analysts, Business managers, CFO
>>>>
>>>> Important Information
>>>> - System initialization and data migration
>>>> - Customization doc - Database, Framework, Tool list, Best Practices
>>>> - Use cases
>>>> - Customization templates - plans,  budget estimating tools
>>>> - System Administration tools and environment docs
>>>>
>>>> The books that are recommended and available should be considered 
>>>> as being owned and read by the team at this point.
>>>> The organization is starting to expend significant resources and 
>>>> purchasing books is the least of the expense.
>>>> This may help reduce the amount of documentation required to be 
>>>> provided by Apache.
>>>> New books could also be created to cover areas not well covered by 
>>>> existing books.
>>>>
>>>> Outdated books should be clearly identified as such with strong 
>>>> recommendations about purchasing them or not and some guidance 
>>>> about which sections are particularly misleading.
>>>> If this is too much work, the book should just be removed from the 
>>>> list of "Books about OfBiz" and if there is any information that is 
>>>> critical and not covered elsewhere, it should be identified as 
>>>> documentation to be created.
>>>>
>>>>
>>>> 4) Development
>>>> At this stage, the implementation team has received the go ahead to 
>>>> implement and has a plan for all customization required.
>>>> The development team is having fun with code and the IT operations 
>>>> group is preparing to purchase any equipment required and is 
>>>> setting up QA sites for integration testing
>>>> Stakeholders : Development team including consultants if required, 
>>>> IT operations
>>>>
>>>> Important Information
>>>> - Customization doc - Database, Framework, Tool list, Best Practices
>>>> - Properly commented code
>>>> - System Administration tools and environment
>>>>
>>>> 5) Implementation
>>>> At this stage the system is put into operation and data is migrated
>>>> Stakeholders : IT Operations, Training, OfBiz Support team
>>>>
>>>> Important Information
>>>> - End-user training material - videos, on-line courses, course 
>>>> templates that can be branded and customized
>>>> - System Administration tools - Security, DR procedures, Update 
>>>> procedures
>>>> - Data migration tools and Best Practices
>>>>
>>>>
>>>> I hope that this helps.
>>>>
>>>>
>>>> On 07/08/2014 7:25 AM, Pierre Smits wrote:
>>>>> Hi all,
>>>>>
>>>>> Newcomers experience problems when they start to participate. This 
>>>>> has been
>>>>> the subject of following stud: http://t.co/bc0gn2SQOZ
>>>>>
>>>>> Do you feel that this project should have an onboarding strategy for
>>>>> newcomers, and if so what should it entail en where should it be 
>>>>> embedded
>>>>> or incorporated?
>>>>>
>>>>> Regards,
>>>>>
>>>>> Pierre Smits
>>>>>
>>>>> *ORRTIZ.COM <http://www.orrtiz.com>*
>>>>> Services & Solutions for Cloud-
>>>>> Based Manufacturing, Professional
>>>>> Services and Retail & Trade
>>>>> http://www.orrtiz.com
>>>>>
>>>>
>>>>
>>>
>>
>>
>


-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102


Mime
View raw message