code/docs co-existing recommendations

[sjay72]

Someone asked me this week if this initiative had any guidance about scenarios where the Community wants docs to be in the same repo as the SW code.

[ncbaratta]

I don't think there would be any difference between a separate docs repo and a repo that is shared with software - but I'm sure we could put something together. I know that @jenmalloy is working this way right now on an upstream project.

[pmkovar]

When docs share a repo with software, the docs build system is often integrated with the software build system. That may allow for automated generation of referential content such as API, configuration options, etc. Cf. OpenStack.

All of this is project-specific, not sure how much detail we want to provide here.

[JStickler]

At a previous job, when I was less experienced with Git, we had docs and code in the same repo. And I ran into problems a couple of times (probably because I wasn't yet diligent about fetching changes from the repo) where when I went to check in my changes and ran into merge conflicts with the code that I didn't know how to resolve. Since a lot of experienced technical writers might be just learning about Git and open source, I think it would be helpful to provide guidance on how to resolve problems like this. Or at least that it's something that they might expect to encounter.

[ncbaratta]

@jenmalloy @fbolton also said they have stories to share about this. We'll need to find a place for this and come up with a way to share guidelines. Any ideas?

[pmkovar]

I think this can be a single topic covering both the repo structure and building, or separate topics that would go into Project Structure and Building Content, respectively.

[ncbaratta]

Just an update here, I have something I can add here and I was asked about this in an interview I did today.

[ncbaratta]

@fbolton @inoxx03 @jenmalloy and I all have experience with this. We might all want to meet to share our ways of doing things.

[pmkovar]

@ncbaratta I'd be also interested. Worked on projects like that before.

[ncbaratta]

Notes:

• Not only what works, but what doesn't work
• What issues might you have
• AMQ git-export script
• Stefan has a script/documentation as well

[inoxx03]

We use a sync script to copy the docs content form the Thorntail upstream repository to launcher documentation.

The procedure for using the script is documented in the Fabric8 Launcher contribution guide: https://launcher.fabric8.io/docs/contrib-guide.html#syncing-with-wildflyswarm-docs_contributing

[jenmalloy]

I'm planning to contribute this content to the community guide: https://docs.google.com/document/d/1Urw4ClA0SlG4Fms4Nu9hSW0VoAITvYrrrQtGAXCECpQ/

[sjay72]

+1 @jenmalloy. Very helpful.

[jenmalloy]

PR submitted: https://github.com/redhat-documentation/community-collaboration-guide/pull/118

[jenmalloy]

Closing this issue, as content is now live: https://redhat-documentation.github.io/community-collaboration-guide/#ccg-considerations-sharing-repo