On Thu, Oct 1, 2015 at 1:02 AM, Oleg Nenashev <o.v.nenas...@gmail.com> wrote:
> Thanks a lot for your feedback regarding the documentation. As you > probably see, it's being reworked now. I'll forward your proposal to Esther > <https://github.com/estheryouhana>, who works on the docs now. BTW, also > feel free to contribute :) > Since the stuff I asked about is not yet in a released version of workflow-plugin, I'm fine, since I realize things are in motion. :) For now, if I have to look inside the tests to figure out the different functions in workflow, that is OK, but that won't be good later on. workflow is different from most plugins, since it is being very heavily promoted by Jenkins core developers. Since workflow is almost a small domain-specific language, enhancing the docs as new functions are added becomes very important. It is great that you have a documentation writer working with the workflow-plugin developers! On Thu, Oct 1, 2015 at 6:07 AM, Jesse Glick <jgl...@cloudbees.com> wrote: > > I am not seeing anything in the test not covered by the help; maybe I am > missing something? > > The wording in the help is technically correct, but i found the code example in the test is more illustrative and easier to understand than the help text. Since things are early stage and moving with workflow, having to look at the code to understand things is OK, but in future, having good docs is important. > > I would recommend as new functions are added to the workflow plugin which >> can >> be called from a workflow script, that they be >> documented in TUTORIAL.md as well. >> > > The original intent (since corrupted somewhat) of that file was to be an > actual tutorial you could follow in document order, trying each revision > for yourself. Forcing it to include every possible step could just become > overwhelming. There are other formats which work better for listing idioms. > Oh OK. Maybe workflow needs both? a TUTORIAL.md which can be followed, and a comprehensive doc which lists all the functions? I don't know the best approach, but since you have a doc writer helping, maybe they can suggest a good approach. -- Craig -- You received this message because you are subscribed to the Google Groups "Jenkins Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/CAG%3DrPVfJW7Q3ETD8afxcV57nNjk0kxJJC38rvbdPD%3D4YnYzDYg%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
