Re: [foreman-dev] Proposal to move "How to create a plugin" page to github.

[sshtein]

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
1. 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).
2. 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 
>

-- 
You received this message because you are subscribed to the Google Groups 
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to foreman-dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[foreman-dev] Proposal to move "How to create a plugin" page to github.

[sshtein]

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:
1. 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.
2. The reviewers could better understand what the PR is offering.
3. 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  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?

-- 
You received this message because you are subscribed to the Google Groups 
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to foreman-dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.