Hi Hans, Totally agree, this will increase the quality of the docs and will make it easier to write and test documentation. It'll be quite a bit of work, but should be done before rather than after 1.0 imho.
Regards, Bart 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 >
