Smoother workflow when writing docs

At the moment the documentation source lives in a separate branch, imaginatively called docs.

So adding features with docs consists of these steps:

1. Fork/pull master
2. Code feature and tests
3. Commit, push and create PR for feature
4. Pull docs
5. Write docs
6. Commit, push and create PR for feature

While not especially difficult or bad, it does seem suboptimal. More importantly, perhaps, it signals a separation between docs and features, where (IMHO) the two should go together - it makes it much easier to discuss a feature if the docs are part of the PR for that feature.

I’m not an expert in Hugo, but from looking at the GH actions defines for deploying docs, it seems like the following should be feasible:

1. Move documentation source away from the docs branch and into master, in a folder called … drumroll … docs.
2. Move all Hugo configuration into that folder as well, in effect making the docs folder be a fully self-contained Hugo site.
3. Change the documentation deploy job to be something like: a. Copy files from the docs folder in master in to the working directory of a CI agent. b. Run Hugo build step against that folder c. Push the build output into the gh-pages branch (like it is done today)

Are there any obvious reasons that I’m missing for why the docs and code are kept separate, and/or something like the above is impossible?

[SeanKilleen]

@isaacabraham

Or am I just complicating things for no real gain?

IMO, yes. 😃

The way I see it, if you have a GitHub issue, and you submit a PR against it for code, you could either include docs in that PR, or submit a separate PR mentioning it. That doesn’t require a separate docs branch and a separate branch could actually complicate it. Plus, the docs “branch” isn’t an actual real branch off of the code, but is currently being treated like a separate mini repo, which IMO is not really in line with how git would intend those things to work.

I wouldn’t worry about a methodical dream of keeping the docs & code in sync. Although, when you tag a release on the master branch, in this new way of doing things, the docs would also be captured as part of that tag at that point in time, which is nice.

I think @hravnx’s suggested approach simplifies things and makes the docs visible in a folder rather than a branch that someone has to know exists. I’d suggest going to there and then re-evaluating if need be.

[SeanKilleen]

Found a historical mention of these options: https://github.com/CompositionalIT/farmer/issues/84#issuecomment-609498633

I think the docs were in a docs branch prior to my involvement, and we kept it that way for inertia’s sake.