Hi all,
Recently I have created a couple of PR's that added extension point to
plugins. These extension point needed to be documented in the
http://projects.theforeman.org/projects/foreman/wiki/How_to_Create_a_Plugin
document.
The problem is that between the time I have created the code PR and the
time it got merged (and the doc change was necessary) passed a couple of
months. I had to remember the context when I was writing the PR in order to
write the wiki page.
I suggest creating a docs PR side by side with the code PR and creating a
reference between them.
Benefits:
- The documentation would be created in the same context by the developer,
while it's fresh in his memory and he remembers all the caveats for the
user.
- The reviewers could better understand what the PR is offering.
- There is less chance for the developer to forget to update the docs
In order to do that, we have to move the page to github (somewhere in
theforeman.org <https://github.com/theforeman/theforeman.org> repo).
To mitigate a concern about the ease of change, we can put a link to edit
the page in the header/footer of the page itself, so it will be one click
away for anyone who wants to edit it.
Comments?
+1, I think it could be added to developer handbook [1] or new section at [2]
or to plugins page [3]
[1] Foreman :: Contribute
[2] Foreman
[3] Foreman :: Plugin Manuals
···
--
Marek
On čtvrtek 22. června 2017 8:48:39 CEST sshtein@redhat.com wrote:
Hi all,
Recently I have created a couple of PR’s that added extension point to
plugins. These extension point needed to be documented in the
How to Create a Plugin - Foreman
document.
The problem is that between the time I have created the code PR and the
time it got merged (and the doc change was necessary) passed a couple of
months. I had to remember the context when I was writing the PR in order to
write the wiki page.
I suggest creating a docs PR side by side with the code PR and creating a
reference between them.
Benefits:
- The documentation would be created in the same context by the developer,
while it’s fresh in his memory and he remembers all the caveats for the
user.
- The reviewers could better understand what the PR is offering.
- There is less chance for the developer to forget to update the docs
In order to do that, we have to move the page to github (somewhere in
theforeman.org https://github.com/theforeman/theforeman.org repo).
To mitigate a concern about the ease of change, we can put a link to edit
the page in the header/footer of the page itself, so it will be one click
away for anyone who wants to edit it.
Comments?
+1 for moving the plugin documentation to the plugins part of the
website. I think that makes sense, and we can (as with other areas)
keep the wiki for footnotes, edge cases, and tips.
Greg
···
On Thu, 2017-06-22 at 09:16 +0200, Marek Hulán wrote:
> +1, I think it could be added to developer handbook [1] or new
> section at [2]
> or to plugins page [3]
>
> [1] https://theforeman.org/contribute.html
> [2] https://theforeman.org/documentation.html
> [3] https://theforeman.org/plugins/
I'd suggest to add a Markdown file to the core repo. I believe code
documentation is better suited to be in the code repo and the
documentation can be reviewed alongside the code change in core by core
maintainers. The website should be more for foreman users. But
theforeman.org is fine with me as well.
···
Am 22.06.17 um 11:16 schrieb Greg Sutcliffe:
> +1 for moving the plugin documentation to the plugins part of the
> website. I think that makes sense, and we can (as with other areas)
> keep the wiki for footnotes, edge cases, and tips.
>
> Greg
>
Having this info in the codebase itself sounds reasonable but I'd prefer
having it on one place with other pages such as template writing wiki. The
later is also useful for users and ideally will be moved to theforeman.org one
day.
If there was a reliable way to sync it from theforeman.org to core codebase,
that would we great. If I had to choose between these two, then I find
theforeman.org better. I think Google would give better results for potential
plugin writers too.
···
> Am 22.06.17 um 11:16 schrieb Greg Sutcliffe:
> > +1 for moving the plugin documentation to the plugins part of the
> > website. I think that makes sense, and we can (as with other areas)
> > keep the wiki for footnotes, edge cases, and tips.
> >
> > Greg
>
> I'd suggest to add a Markdown file to the core repo. I believe code
> documentation is better suited to be in the code repo and the
> documentation can be reviewed alongside the code change in core by core
> maintainers. The website should be more for foreman users. But
> theforeman.org is fine with me as well.
>
> - Timo
–
Marek
Timo,
Since we already are using the site to host the handbook, I think it would
be nice if plugin writing guidelines would be there too.
If we look at plugin writers as "core users", would the site be better
suited for the task? 
For the development workflow:
First, if the docs PR is mentioned in the code PR (as it should), Github
makes it pretty easy to follow the link for the code maintainer.
IMHO there are two advantages for different repos
- The docs PR is exposed to additional maintainers that could give
additional input about the quality of the documentation itself (like
styling, english e.t.c).
- It decouples the lifecycles of the changes. Let's say that the code is
already perfect, but the docs still need some work. I don't think we should
not merge the code and wait for the docs to mature.
Marek,
I think a simple link in our readme file would be a quite good compromise
for syncing code and docs repos. I suggest either "Plugins" or "How to
contribute" chapters. It should also increase the visibility of the page.
+1 to google optimization
About template writing wiki: I don't want to derail this thread, but after
we agree on a place for plugin writing wiki, I can start another one for
template writing as well. One issue per commit, isn't it
···
On Friday, June 23, 2017 at 9:36:56 AM UTC+3, Marek Hulán wrote:
>
> > Am 22.06.17 um 11:16 schrieb Greg Sutcliffe:
> > > +1 for moving the plugin documentation to the plugins part of the
> > > website. I think that makes sense, and we can (as with other areas)
> > > keep the wiki for footnotes, edge cases, and tips.
> > >
> > > Greg
> >
> > I'd suggest to add a Markdown file to the core repo. I believe code
> > documentation is better suited to be in the code repo and the
> > documentation can be reviewed alongside the code change in core by core
> > maintainers. The website should be more for foreman users. But
> > theforeman.org is fine with me as well.
> >
> > - Timo
>
> Having this info in the codebase itself sounds reasonable but I'd prefer
> having it on one place with other pages such as template writing wiki. The
> later is also useful for users and ideally will be moved to theforeman.org
> one
> day.
>
> If there was a reliable way to sync it from theforeman.org to core
> codebase,
> that would we great. If I had to choose between these two, then I find
> theforeman.org better. I think Google would give better results for
> potential
> plugin writers too.
>
> --
> Marek
>
