No internet connection
  1. Home
  2. Support

Integrate static documentation

By Andreas Pieber @pieber
    2020-04-04 14:13:14.040Z

    I have a documentation generated from asciidoc which produces a manual in PDF and in static html page. Talkyard provides the Q&A page for using the product. Most answers will reference the manual again. Basically we just open the manual and the Q&A to real users of the product which need to be invited by us.

    Therefore it sounds kind of very attractive if Jenkins could push the documentation to talkyard where it could be viewed and referenced. In addition it would be perfect if the manual and the Q&A section could be searched for similar questions/content and therefore reduce the work required by the support team?

    Is there already an option for setting up something like this? Could the code be easily extended for such a use case?

    Reply1 Like
    • 4 replies
    1. KajMagnus @KajMagnus2020-04-06 12:00:17.665Z

      if Jenkins could push the documentation to talkyard

      Interesting idea. Sounds like upserting HTML pages into Talkayrd? Talkyard has an API for inserting pages — I would need to make this work also for updating already existing pages too.

      Your asciidocs, it generates a single HTML page? Or many small pages?

      Any thoughts about people posting questions directly on the documentation pages?
      (I'm thinking this 1) can be quite nice for the end users — and at the same time, 2) makes it "risky" to reorganize the docs — for example, what's going to happen with people's questions, if a docs page gets split into two smaller pages.)

      ( @chrscheuer at SoundFlow uses this upsert-pages API so that the SoundFlow users can suggest ideas etc related to SoundFlow.)

      it would be perfect if the manual and the Q&A section could be searched for similar questions/content and therefore reduce the work required by the support team?

      Yes I think so too. I need to write docs for Talkyard, and I've been wondering how to make the docs searchable from inside the Talkyard forum. Maybe upserting the docs into Talkyard as static pages is a good solution.

      What I was thinking about, was a 2nd approach: (but now I think I like your idea better — at least it's (a lot?) simpler to implement)

      • Generating the static HTML docs as usual.
      • Optionally adding Talkyard embedded comments at the end of each docs page, so people can post questions there.
      • Somehow telling Talkyard to full-text-search-index those static HTML pages, so their contents becomes searchable from within Talkyard. (Although they are external pages.)
      Reply1 Like
      1. CChristian Scheuer @chrscheuer
          2020-04-06 12:05:56.324Z

          This is an interesting approach for documentation. We never thought of hosting our docs inside Talkyard before - I'll think about if that's something we want to do as well.
          Regardless - search is super, super important as the content grows.
          We're in the thousands of Q/A's now, and it becomes more and more important that we can integrate Talkyard search into our other products. Strictly speaking a Talkyard search API could also help with the OP, while it's not what Andreas asked for.

          Reply
          1. CChristian Scheuer @chrscheuer
              2020-04-06 12:07:50.916Z

              But I also agree with you Magnus, that the upsert approach to pages should be the way to go.

              Reply
            • In reply toKajMagnus⬆:
              PAndreas Pieber @pieber
                2020-04-08 21:46:53.181Z

                I rather thought about many pages since it will get REALLY long otherwise and even longer to load. The PDF we're generating from the same base has about 250 pages right now, which would take kind of forever to load on bad internet connections...

                But this also add some additional challenges:

                1. Pages could also be deleted
                2. I do not really have an index of all the pages

                What would be ideally: put a zip-file with html-pages to an endpoint, e.g. docs, which automatically updates/syncs the entire tree behind this endpoint and also updates the index/search for all those sites (even deleting pages in the current tree but missing in the uploaded zip). Ideally this endpoint would also check the hashes of the pages making sure that only changed pages get updated/reindexed.

                Resulting from this workflow, I don't think it's practically allowing comments there. What happens if the page gets deleted, moved, separated, - and this is not so unlikely to happen. I rather plan attaching two links to the bottom of every page:

                1. Don't you find what you are looking for? Create a question here [link to the Q&A Forum]
                2. Found any problem/error on this page. Drop us a message [mail:to:support]

                Does this sound interesting to you?

                Reply
              ReplyAdd progress note