Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Smoother workflow when writing docs

See original GitHub issue

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 … drumrolldocs.
  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?

Issue Analytics

  • State:closed
  • Created 3 years ago
  • Comments:21 (21 by maintainers)

github_iconTop GitHub Comments

SeanKilleencommented, May 25, 2020


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.

SeanKilleencommented, May 25, 2020

Found a historical mention of these options:

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

Read more comments on GitHub >

github_iconTop Results From Across the Web

Documenting Workflows: Benefits, Mistakes & How to ...
Write down the necessary steps or changes to be made in each situation to ensure a smooth workflow. 8. Document tools and resources....
Read more >
The Ultimate Workflow for Writers Obsessed with Quality
A seven-step workflow for writing, to ensure quality every time (plus the essential tools and software you need to make it happen)
Read more >
How to Create and Document a Workflow
Learn how to write an effective workflow for your business and download free, customizable workflow templates as Adobe PDF files.
Read more >
From Chaos to Clarity: Streamlining Workflow Documentation
Adopting a strategic approach to workflow documentation can transform chaos into clarity and streamline your operations for maximum efficiency.
Read more >
How to Create Document and Workflow for Business Process
Steps involved in workflow documentation · Plan content outline · Write content · Prepare illustrations / diagrams · Review content · Seek approval ......
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found