+1 from me as well Hans. It's a great idea. Sometimes I think it's better to just do the work in the short term to avoid the accumulated pain over time. I certainly didn't have a lot of fun updating docs in the source code (plugin information) along with their navigation and index pages in the docs and so on. What you propose would solve most of the issues I was having. Cheers, Matt
On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <[email protected]> wrote: > Hi All, > > When we started this project we started with a separate documentation > repository [1]. > > While this seemed a great idea at the time I would like to come back to > this subject. I would like to propose to merge our documentation to our > source code repository. > > There are three main advantages: > - Single source for releases > - Simpler testing > - More advanced asciidoc features > > When creating a release we will automatically have a branch that contains > the documentation that is valid for that release, at this point in time > this is a non-issue as we are not yet creating versions of our > documentation and everything is still aligned, but when we move forward > parts of the documentation will become deprecated or linked to a specific > version. > > If we single source our documentation we can include a basic version of our > documentation website to our code repository this will make it simpler to > see what the end result will look like. It allows you to do changes in an > adoc file and instantly see the new version in a browser the same way it > will be represented on the website. > > Asciidoc has features where you can include snippets/classes/methods of > your source code in your documentation, they are dynamically linked. This > means that if the method changes the docs will be updated instantly. Though > we would have to test if these features work in our current setup this can > be a great addition to our developer documentation. > > As always this mail is to gather feedback and your opinion on the matter > before we start changing things. > > Cheers, > Hans > > [1] https://github.com/apache/incubator-hop-docs >
