Re: Proposal: Migrating docs to Asciibinder framework

Ronny Trommer <[email protected]> Tue, 19 Sep 2017 23:37:16 +0200
Newsgroups	gmane.network.opennms.general
Message-ID	<[email protected]>
Status Update

I have cleaned up the branch and removed the old opennms-doc directory from the branch. I’ve added also a first minimal stylesheet to look more like something OpenNMS-ish. We have Wednesday evening our OpenNMS internal sprint meeting and I’ll bring this topic up, so we can decide how to move forward.

Here are the things which reflect the current status of the branch jira/NMS-9495:

- Migrate everything in opennms-doc directory to AsciiBinder which is now the docs directory: DONE
- Merge user/admin/developer docs to make it easier to find things: DONE
- Deploy the current state to a public website for testing[1][2]: DONE
- Add deployment mechanism to Bamboo and auto-publish on release (OPEN)

Suggestions as next steps when we have it migrated:

- Cleanup our release notes. we only need the Changelog and What’s new for the current version. For the reason the docs are versioned along with the software the history will build up by himself. Currently we drag the whole history of versions through our docs
- Brainstorm and rethink the generic structure, we have now all in one place and we need to refactor things to make it easier to navigate and more obvious to find things you are looking for
- Refactor* most important guides like the installation in better usable use-case driven Step-by-Step walkthroughs, for example:
 	- “How to install on CentOS”
	- “How to create Surveillance View”
	- “How to create Wallboard for Screen Rotation”
	- “How to manage Node in a Requisition”
	- “How to add a new service monitor”
	- “How to collect performance data from a SNMP device"
- Remove screenshots as much as we can and describe it instead to increase maintainability, e.g. like AWS CodeDeploy[3]
- We have to think about the ReST API documentation, currently it is manually and we should definitely consider to use something like Swagger[4], RAML[5] or API Blueprint[6], the current manual created ReST API documentation is outdated and does not contain anything about the new introduced v2 API

Please feel free happy to get your feedback about it and if you are interested to contribute in one of the topics. I personally would prefer to move quickly from a “migrating something from tech A to B task" to a more content and structure driven work mode, content matters and there are a lot of interesting things to do :D

So far with greetings from Germany

[1] https://docs.opennms.eu/horizon/NMS-9495/about/index-opennms.html
[2] http://docs.internal.opennms.eu/minion/NMS-9495/about/index-minion.html <http://docs.internal.opennms.eu/minion/NMS-9495/about/index-minion.html>
[3] http://docs.aws.amazon.com/codedeploy/latest/userguide/tutorials-windows-update-and-redeploy-application.html#tutorials-windows-update-and-redeploy-application-deploy-updates-console <http://docs.aws.amazon.com/codedeploy/latest/userguide/tutorials-windows-update-and-redeploy-application.html#tutorials-windows-update-and-redeploy-application-deploy-updates-console>
[4] https://swagger.io/docs/specification/about/
[5] https://raml.org
[6] https://apiblueprint.org/documentation/

*When I say refactoring, that always means not just adding stuff also deleting, the goal after refactoring is having less :)

> On 13. Sep 2017, at 01:54, Ronny Trommer <[email protected]> wrote:
> 
> Hello Everyone,
> 
> I’ve worked during DevJam 2017 to migrate our documentation from the plain Java based AsciiDoctor [1] to the AsciiBinder framework [2]. It addresses some more publishing and managing docs. It is used in projects like OpenShift, Atomic and is currently also in a evaluation phase for Fedora. The proposal is a little bit more described in the Wiki [3].
> 
> I’ve finished and cleaned up the work and you can find the proposed new structure in the branch lira/NMS-9495 [4][5]. To build the docs you need to install a ruby gem asciibinder. The new documentation structure is moved from opennms-docs which was build by maven into the docs folder.
> 
> Once you have it installed asciibinder you can clone the opennms git repo, change into the docs directory and run asciibinder package. If you want I’ve published the HTML output a public location [6][7]. So you can play around with.
> 
> Other than migration, I’ve noticed it is hard to find things, so I’ve decided to merge the install, admin and user guide. What we have noticed, we should reconsider and consolidate the overall structure without getting the overall structure too deep.
> 
> A first goal could be to publish the documentation similar as we did with Helm[8]
> 
> If you want to join in or want to give some feedback please let me know, I’m hanging out in the chat [9] and happy to talk about it. PRs against the branch are always welcome so feel free :)
> 
> Ronny
> 
> [1] http://asciidoctor.org
> [2] http://www.asciibinder.org
> [3] https://wiki.opennms.org/wiki/Proposals/AsciiBinder
> [4] https://github.com/OpenNMS/opennms/tree/jira/NMS-9495
> [5] https://issues.opennms.org/browse/NMS-9495
> [6] https://docs.opennms.eu/horizon/NMS-9495/about/index.html
> [7] https://docs.opennms.eu/minion/NMS-9495/about/index.html
> [8] http://docs.opennms.org/helm/branches/master/helm/latest/welcome/index.html
> [9] https://chat.opennms.com/opennms/channels/opennms-discussion
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot_______________________________________________
> Please read the OpenNMS Mailing List FAQ:
> http://www.opennms.org/index.php/Mailing_List_FAQ
> 
> opennms-discuss mailing list
> 
> To *unsubscribe* or change your subscription options, see the bottom of this page:
> https://lists.sourceforge.net/lists/listinfo/opennms-discuss

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

_______________________________________________
Please read the OpenNMS Mailing List FAQ:
http://www.opennms.org/index.php/Mailing_List_FAQ

opennms-discuss mailing list

To *unsubscribe* or change your subscription options, see the bottom of this page:
https://lists.sourceforge.net/lists/listinfo/opennms-discuss
signature.asc (application/pgp-signature, 496 B)