Hi, +1, I think it will be easier to sync the documentation with the source code.
regards, François [email protected] Le 10/04/2021 à 19:38, Bart Maertens a écrit : > 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 >>
