[jira] [Commented] (OFBIZ-6015) Move Online Help Documentation from Webhelp into Trunk

[Ron Wheeler (JIRA)]

[ 
https://issues.apache.org/jira/browse/OFBIZ-6015?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=14900577#comment-14900577
 ] 

Ron Wheeler commented on OFBIZ-6015:


in response to the question  "Can anyone please provide suggestions on how to 
implement the
automatic generation of documents from GIT?" this response was created in  the 
DITA users forum with links to 2 articles that might be helpful for us.

--

I’ve given a few conference presentations on Automating DITA Builds
over the past few years. You may find this information useful as you
investigate automation options for your project.

The slides from my talk at DITA North America in Seattle last year are
available here:
.

The presentation was expanded to an article for the CIDM Best Practices
Newsletter:
.

Both outline various automation approaches, including Git hooks and
continuous integration servers like Jenkins (as Radu suggested). Code
samples are included that you can use to trigger builds when you commit
changes to Git.

Hope that helps,

Roger


P.S.

The DITA For Small Teams project 
is also putting together a series of sample projects and resources that
can be used to automate the build process. There has been some
discussion lately about preparing Docker containers that would provide a
pre-configured DITA-OT and Jenkins, but I’m not sure how far that idea
has come. 

> Move Online Help Documentation from Webhelp into Trunk
> --
>
> Key: OFBIZ-6015
> URL: https://issues.apache.org/jira/browse/OFBIZ-6015
> Project: OFBiz
>  Issue Type: Sub-task
>  Components: ALL APPLICATIONS
>Reporter: Sharan Foga
>Assignee: Sharan Foga
>Priority: Minor
> Attachments: Webhelp Analysis.ods
>
>
> This Jira has been created to manage the migration of all the documentation 
> from the Webhelp branch into the current help system so that it will work 
> with what we already have (essentially so that we dont lose it!).  The 
> original issue for the Webhelp is 
> https://issues.apache.org/jira/browse/OFBIZ-4941
> As well as HR, there is also online documentation for Accounting, 
> Manufacturing (English, German and Dutch), Project Manager and Catalog - 
> though not as complete, so I will be consolidating and moving those too. The 
> files use the docbook format and are compatible with what we have although he 
> implemented everything into one file (i.e book) per module. I now think this 
> is the better way to go.
> Update as at July 2015
> ==
> The original code from the Webhelp branch was updated and converted to an 
> OFBiz addon. 
> The addon was created from the Webhelp branch but is setup as an addon.
> To see a what the webhelp will look like and function like. 
> Go to https://demo.ofbizextra.org/accounting/control/main
> Login as admin/ofbiz
> Select HR and then click the help button (The docbook webhelp should be 
> displayed)
> As well as using docbook and webhelp for displaying it. Some additonal 
> funcitonality has been added. These are as follows:
> 1) There are some ant targets created (e.g. ant webhelp, clean-webhelp)
> 2) There is a flag setup to indicate whether a module has webhelp or uses 
> OFBiz standard help (i.e. what we are using now). 
> To test it on the ofbizextra demo 
> Select Facilities and then click the help button (The normal OFBiz help menu 
> is displayed because no webhelp exists for this module)
> I think this could be good thing as we convert the existing documentation 
> from the current online help format to the webhelp because it wont break 
> anything and leaves the option open for people who are using the existing 
> help system.
> 3) There is also some functionality related to language that looks at the 
> language of the user to see if the webhelp exists in that language. If it 
> doesn't there is a message saying so but that documentation exists in another 
> language 
> The addon uses the patch Files. (.patch) I think this is because the addon 
> tries to maintain compatibility with different OFBiz versions but I think 
> it's still just xml or java code.
> I have done an initial (non technical) analysis of the files and attached 
> that too



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Commented] (OFBIZ-6015) Move Online Help Documentation from Webhelp into Trunk

[Sharan Foga (JIRA)]

[ 
https://issues.apache.org/jira/browse/OFBIZ-6015?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14649376#comment-14649376
 ] 

Sharan Foga commented on OFBIZ-6015:


I've had no feedback on this so it sounds like it's not in an easy format for a 
technical review. I will work on converting the Webhelp Addon code from the 
.patch file formats into a SVN patch file to make it easier to install, test 
and review.

 Move Online Help Documentation from Webhelp into Trunk
 --

 Key: OFBIZ-6015
 URL: https://issues.apache.org/jira/browse/OFBIZ-6015
 Project: OFBiz
  Issue Type: Improvement
  Components: ALL APPLICATIONS
Reporter: Sharan Foga
Assignee: Sharan Foga
Priority: Minor
 Attachments: Webhelp Analysis.ods


 This Jira has been created to manage the migration of all the documentation 
 from the Webhelp branch into the current help system so that it will work 
 with what we already have (essentially so that we dont lose it!).  The 
 original issue for the Webhelp is 
 https://issues.apache.org/jira/browse/OFBIZ-4941
 As well as HR, there is also online documentation for Accounting, 
 Manufacturing (English, German and Dutch), Project Manager and Catalog - 
 though not as complete, so I will be consolidating and moving those too. The 
 files use the docbook format and are compatible with what we have although he 
 implemented everything into one file (i.e book) per module. I now think this 
 is the better way to go.
 Update as at July 2015
 ==
 The original code from the Webhelp branch was updated and converted to an 
 OFBiz addon. 
 The addon was created from the Webhelp branch but is setup as an addon.
 To see a what the webhelp will look like and function like. 
 Go to https://demo.ofbizextra.org/accounting/control/main
 Login as admin/ofbiz
 Select HR and then click the help button (The docbook webhelp should be 
 displayed)
 As well as using docbook and webhelp for displaying it. Some additonal 
 funcitonality has been added. These are as follows:
 1) There are some ant targets created (e.g. ant webhelp, clean-webhelp)
 2) There is a flag setup to indicate whether a module has webhelp or uses 
 OFBiz standard help (i.e. what we are using now). 
 To test it on the ofbizextra demo 
 Select Facilities and then click the help button (The normal OFBiz help menu 
 is displayed because no webhelp exists for this module)
 I think this could be good thing as we convert the existing documentation 
 from the current online help format to the webhelp because it wont break 
 anything and leaves the option open for people who are using the existing 
 help system.
 3) There is also some functionality related to language that looks at the 
 language of the user to see if the webhelp exists in that language. If it 
 doesn't there is a message saying so but that documentation exists in another 
 language 
 The addon uses the patch Files. (.patch) I think this is because the addon 
 tries to maintain compatibility with different OFBiz versions but I think 
 it's still just xml or java code.
 I have done an initial (non technical) analysis of the files and attached 
 that too



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Commented] (OFBIZ-6015) Move Online Help Documentation from Webhelp into Trunk

[Sharan Foga (JIRA)]

[ 
https://issues.apache.org/jira/browse/OFBIZ-6015?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14614234#comment-14614234
 ] 

Sharan Foga commented on OFBIZ-6015:


Webhelp code attachment is too large for Jira

 Move Online Help Documentation from Webhelp into Trunk
 --

 Key: OFBIZ-6015
 URL: https://issues.apache.org/jira/browse/OFBIZ-6015
 Project: OFBiz
  Issue Type: Improvement
  Components: ALL APPLICATIONS
Reporter: Sharan Foga
Assignee: Sharan Foga
Priority: Minor
 Attachments: Webhelp Analysis.ods


 This Jira has been created to manage the migration of all the documentation 
 from the Webhelp branch into the current help system so that it will work 
 with what we already have (essentially so that we dont lose it!).  The 
 original issue for the Webhelp is 
 https://issues.apache.org/jira/browse/OFBIZ-4941
 As well as HR, there is also online documentation for Accounting, 
 Manufacturing (English, German and Dutch), Project Manager and Catalog - 
 though not as complete, so I will be consolidating and moving those too. The 
 files use the docbook format and are compatible with what we have although he 
 implemented everything into one file (i.e book) per module. I now think this 
 is the better way to go.
 Update as at July 2015
 ==
 The original code from the Webhelp branch was updated and converted to an 
 OFBiz addon. 
 The addon was created from the Webhelp branch but is setup as an addon.
 To see a what the webhelp will look like and function like. 
 Go to https://demo.ofbizextra.org/accounting/control/main
 Login as admin/ofbiz
 Select HR and then click the help button (The docbook webhelp should be 
 displayed)
 As well as using docbook and webhelp for displaying it. Some additonal 
 funcitonality has been added. These are as follows:
 1) There are some ant targets created (e.g. ant webhelp, clean-webhelp)
 2) There is a flag setup to indicate whether a module has webhelp or uses 
 OFBiz standard help (i.e. what we are using now). 
 To test it on the ofbizextra demo 
 Select Facilities and then click the help button (The normal OFBiz help menu 
 is displayed because no webhelp exists for this module)
 I think this could be good thing as we convert the existing documentation 
 from the current online help format to the webhelp because it wont break 
 anything and leaves the option open for people who are using the existing 
 help system.
 3) There is also some functionality related to language that looks at the 
 language of the user to see if the webhelp exists in that language. If it 
 doesn't there is a message saying so but that documentation exists in another 
 language 
 The addon uses the patch Files. (.patch) I think this is because the addon 
 tries to maintain compatibility with different OFBiz versions but I think 
 it's still just xml or java code.
 I have done an initial (non technical) analysis of the files and attached 
 that too



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Commented] (OFBIZ-6015) Move Online Help Documentation from Webhelp into Trunk

[Ron Wheeler (JIRA)]

[ 
https://issues.apache.org/jira/browse/OFBIZ-6015?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14282960#comment-14282960
 ] 

Ron Wheeler commented on OFBIZ-6015:


Topic-based writing seems like a good way to build documentation and encourages 
reuse rather that copy and paste.
Splitting up the documentation into sections based on screens/business 
processes with concepts as separate fragments will make the use of the 
documentation for various purposes (on-line help, program specifications, 
training, manuals, job-aids, etc.) much easier.
It may also encourage developers and business consultants to contribute 
fragments from user requirements, design specifications or even design 
discussions that can be used to construct documents.
The big issue here is naming and tagging fragments so that it is easy to find 
the pieces that you want.
The initial suggestion about using the SCM (SVN) to store them only works if 
the documentation team has write access and can manage the structure of the 
fragments easily. A CMS would be a better choice. If the document production 
steps can support access to fragments in the CMS, that would be ideal.



 Move Online Help Documentation from Webhelp into Trunk
 --

 Key: OFBIZ-6015
 URL: https://issues.apache.org/jira/browse/OFBIZ-6015
 Project: OFBiz
  Issue Type: Improvement
  Components: ALL APPLICATIONS
Reporter: Sharan Foga
Assignee: Sharan Foga
Priority: Minor

 This Jira has been created to manage the migration of all the documentation 
 from the Webhelp branch into the current help system so that it will work 
 with what we already have (essentially so that we dont lose it!).  The 
 original issue for the Webhelp is 
 https://issues.apache.org/jira/browse/OFBIZ-4941
 As well as HR, there is also online documentation for Accounting, 
 Manufacturing (English, German and Dutch), Project Manager and Catalog - 
 though not as complete, so I will be consolidating and moving those too.
 The files use the docbook format and are compatible with what we have 
 although he implemented everything into one file whereas we use one file per 
 screen - so I'll need to split it up.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)