[opennms-discuss] FYI: [Summary] Documentation Meetup cw30/2014

[Ronny T. <ro...@op...>]

Hi Guys,

we had our second bi-weekly doc meeting this evening. We talked about the following topics:

Current status quo
------------------------
- We aimed for an issue driven GitHub Pull requests workflow
 Special thanks to Ian and Cyrille who helped working out a pull-request / patch based GitHub workflow
- Branches are named in the following pattern <NMS-number_docs_MonitorName>
- During the first phase we started a draft for a documentation guideline[1] which should help to get you over the hump. It tackles different topics, like formatting conventions and even a short introduction with examples how to use AsciiDoc.
- Pull requests are made against the opennms repository branch “development/docs”
- Pull request is reviewed by second person and after review phase merged to “development/docs”
- Ben configured OpenNMS Bamboo to pick up merged pull requests, they will be compiled and deployed doc to a public location[3]
- The Wiki page structure for “How to contribute docs”[4] to solve the first entry level questions is improved. The structure is much clearer now.
- We have a Wiki template[5] for monitors which are currently in progress and are migrated to the official doc
- Status “Resolved” is used as merged to “development/docs” and published
- Status “Closed” is used as camera ready and reviewed for conventions and language issues
- Currently: 17 of 71 monitors are documented[2]
- We where able to get the meeting down from 2h to 1.5h :D

Issues and problems
---------------------------
- It is not possible to assign a JIRA task. You need special permissions to assign external user to tasks. So they can’t start a task as in progress
- Links are inconsistent on the OpenNMS.org events section[6] and the wiki events section[7]
- We talked about detectors and monitor documentation. We can remove detector/capsd and other behaviours from the monitor documentation. Creating similar section for detectors and use links if a detector exist for a given monitor
- Problems dealing with JIRA issues is a higher barrier. Evaluation if there is a possibility for an easy to use simple web form creating an issue in JIRA
- Language support in docs: There are possibilities but not focused right now.
- Embedding external content in the wiki has some security implications, XSS etc. In longterm the Wiki documentation should be slimmed down.
- Having a stable links to versions of documentation for external links, 
http://docs.opennms.org/guide-admin/stable —> http://docs.opennms.org/guide-admin/1.12.8
http://docs.opennms.org/guide-admin/testing —> http://docs.opennms.org/guide-admin/1.12.9
http://docs.opennms.org/guide-admin/unstable —> http://docs.opennms.org/guide-admin/1.13.3
http://docs.opennms.org/guide-admin/snapshot —> http://docs.opennms.org/guide-admin/1.13.4
- We haven’t checked homework[8]

Goals for the next 2 weeks
-----------------------------------
- Installing the categories plugin in MediaWiki on opennms.org
- Finding a way improving the JIRA workflow for external users, assignment, unassignment, start in progress etc.
- Improve documentation guide with describing the GitHub pull request workflow[9]
- Documentation more monitors, what done is, is done [2]
- Improving documentation guide from native language perspective (no JIRA issue yet)
- Review already documented monitors (no JIRA issue yet)

If there is something missing, just reply to the mail on the opennms-docs list
The procedure for cw32 is the same as usual. I’ll send out a doodle to opennms-docs and opennms-discuss

Thank you guys for spending your time and have a nice week.

[1] http://docs.opennms.org/guide-doc/1.13.4-SNAPSHOT/index.html
[2] http://issues.opennms.org/browse/NMS-6634
[3] http://docs.opennms.org/
[4] http://www.opennms.org/wiki/How_to_contribute_to_documentation
[5] http://www.opennms.org/wiki/Template:WIP
[6] http://www.opennms.org/
[7] http://www.opennms.org/wiki/OpenNMS:Current_events
[8] https://www.youtube.com/watch?v=vx5n21zHPm8
[9] http://issues.opennms.org/browse/NMS-6740