docs.hornbill.com issue

[samwoo]

Hi @Gerry,

Rather than hijacking the other thread, I've decided to post it in here. 

For reference, I am using the latest version of Microsoft Edge (Business).

When clicking on the link you provided on the other chat, this time, it briefly showed the page, then went directly to 502 Bad Gateway.

This is what I see in Network just before page started to load:

When refreshing, the page loads as normal.

Thanks,

Samuel

[Berto2002]

Yes I get the same issue when using a link (https://docs.hornbill.com/esp-fundamentals/core-capabilities/organization-and-teams

[Gerry]

Thanks guys, it seems we have a problem with one of our docs servers being down and the load balancer not doing its thing. We will sort that, thank you for posting the information.

 

Gerry

[samwoo]

No problem at all @Gerry, very happy to assist. 

Loving docs.hornbill.com and can't wait for more information on there so we can start using it more  

[Gerry]

@samwoo

First off, thanks for the feedback, if you have suggestions or comments, (or even the burning desire to contribute lol) please let us know, its early days so we are cranking out quite a lot of internal and unpublisjed documentation, we are looking to abandon the wiki as soon as we can.   The new documentation system is built by us, purpose built for the job and that, coupled with the academy we have also created, are both being invested in so we can get high quality learning and reference content to our customers.  Work in progress and pleanty more to come. 

With regards to the 502 error, we have now resolved that, it was a crashing issue, our systems are robust enough to be laod balanced so while it was not taking the thing down the proxy was seeing unexpectedly dead connections, this has now been resolved. 

We have also resolved the issue that was not opening the document when you clicked the link, so thats also sorted.  

@samwoo @Berto2002 If you would be so kind as to conrm its working for you now I would appreciate it: https://docs.hornbill.com/esp-fundamentals/core-capabilities/organization-and-teams

Gerry

[samwoo]

@Gerry,

No problem at all., happy to help.

In fact, I do have a suggestion for improvement, but I am not sure how feasible it is to implement, but have you considered allowing people to comment on the documentation pages on docs.hornbill.com?

• We, your customers, can engage in discussions on documentation topics to promote knowledge sharing and feedback
  • Comments are moderated, like the forums, and moderators can get involved in the discussions as well.
• Customers can report any issues with the documentation to moderators via the comments
  • Could it be possible for Moderators can raise a GitHub issue from a comment, this could be if a customer reports out of date instructions, or requests improvements for example (let's face it, it is difficult to keep documentation maintained to 100% perfection, so we can help you if we spot something out of date for example).
  • Contributors would be more involved with the documentation, whereas people can also make comments without being contributors via Github and still be able to help out.

I can confirm the issues reported earlier is now resolved. The page does do a little dance where it loads the content... when the page loads, it briefly clears the contents then loads the contents again but it's no showstopper and doesn't cause any issues.

Thanks,

Samuel

[samwoo]

Hi again @Gerry Another suggestion, which might be overkill... but is it possible to include a changelog of changes made to docs.hornbill.com, with linkback to the pages/sections that were created/amended? 

[Gerry]

@samwoo

Thanks for the suggestions/questions.  Its incredibly important to foster as much customer engagement as possible when it comes to documentation, I would love it if customers had everything they needed to hand, and our support team only ever answered questions with links to the documentation   pipe dream I know, but reach for the stars and all that...

Discussions : this is on the list of things to consider.  Thus far the system does not use a database, content is built from Github repo's and published.  In order to implement discussions we would either need to integrate something like Disqus or we need to roll our own.  One of the things for consideration is to enable comments powered by Hornbill collaboration/workspaces, as we use these internally already so its a ready-made back end.  Basically, either a workspace or seeded post per document. where a discussion.  There are various issues around moderation and of course keeping track of issues that need to be addressed, so there is some work to do here, but yes thats most definitely on the cards. 

Reporting Issues: As above, it would be nice if the above mechanism could be used, basically raising an issue would post into a workspace where we can manage it.  So I want to say on the cards also.  

ChangeLog: Not that we have a plan, but this has most definitely been in our thoughts, you will note that every document is versioned (bottom of the page) and, internally at least we have an identity system so we know who (internally) is reading what documents, so we could record that in a database, if we can extend the identity system to our community, then the same.  Then, because we would know who has seen what version of each document, when a document is published and has a new version we could work out who we need to notify, and perhaps make that available in a change log, a daily digest email or some other mechanism.   The ChageLog could not be based on Git comments, because there a lot of minor tweaks often, spelling, typos and the like, which would drive people crazy, so it would need to be more like our release notes which are declarative and written by the auther each time they change the document.  Something we could do, even if we have community contributed content.  So yes, this too would be a very nice addition to the docs system for sure. 

I can't make promises with this stuff at the moment, in many respects, outside of the intial push, the docs system is a bit of a home-grown side project here at Hornbill because its not our main dev activity it only gets the attention it needs ATM. One thing for sure though, is every day the documentation is more and more important and valuable as more and more content is created, so you will for sure see this evolve. 

Thanks for the suggestions and watch this space. 

Gerry