Re: Proposal: Migrating docs to Asciibinder framework

One thing that's missing from the AsciiBinder layout is the ability to search. With the current single document layout,
I find myself using Ctrl+F and searching for keywords to locate the content, but this is no longer possible with the new
layout.

The OpenShift documentation at https://docs.openshift.com/online/welcome/index.html, also based on AsciiBinder, provides
this capability. Perhaps we could implement something similar?

-Jesse


On 09/19/2017 05:37 PM, Ronny Trommer wrote:
> 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
> [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
> [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] <mailto:[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://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

------------------------------------------------------------------------------
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