61–70 of 134 posts
The process was mostly just changing out a Jenkins file to the GitHub yml and sorting a few issues that cropped up.
Earlier quoted context omitted.
I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly: "Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in dif…
What is the difference between a tutorial and a how-to guide?
but to summarize...
A tutorial: - is learning-oriented - allows the newcomer to get started - is a lesson
A how-to guide: - is goal-oriented - shows how to solve a specific problem - is a series of steps
Earlier quoted context omitted.
I assume you’re talking about Go here?
Possibly Typescript. Try finding documentation for the bundled "Record" type. It seems you're supposed to just know how to use it already.
Earlier quoted context omitted.
I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly: "Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in dif…
What is the difference between a tutorial and a how-to guide?
Earlier quoted context omitted.
Thanks for the warning, are there any good tools that integrate with pull request checks that can be self hosted? We self host nearly everything at work except for github. (And it's VERY difficult for me to get anything that costs money approved regardless of price)
And it's VERY difficult for me to get anything that costs money approved regardless of price For me, this is a big red flag.
The response I get is we don't _NEED_ a CI/CD (and haven't had one for years), so they would rather I find a solution that can run on our hardware for free.
I'll add that I enjoy my work environment and they treat me very well, I'm young and I'm known to "like shiny new things". I also have to work on how I pitch why we need certain things, again I'm pretty young so I'm not well practiced in that just yet.
Earlier quoted context omitted.
Someone please tell the Google Cloud Platform teams this. So many hello world examples which reek of, "I was told to write documentation but I really hate writing documentation". I mean this in good faith, I think writing documentation for a product you don't actually use is a miserable experience and I hope they can find a better balance... Writing documentation also seems to be a task you kick out to your junior de…
If there's one documentation that I hate with my gut, that is GCP documentation. Like wtf is going on there. Just to give you an example of how horrible it is, just check their Vision documentation: https://cloud.google.com/vision/docs/ They have quick starts, tutorials and how-to-guides. How are even those things conceptually different at all?. And their reference is just a list of their methods like if I knew out o…
The API reference in particular you pointed to has a top-level description + linkable reference to each individual method / resource along with brief description. AND, for older versions, as well as a description of "objects" used in the API. I guess it would have been nice to also have a sandbox playground, like some of their other APIs do, but this one is fairly good?
Just curious, what's an example of great API in your mind?
*(possibly not in-depth enough, but I wouldn't be able to tell as a newbie).
I'd be hesitant to build on GitHub tools that have overlap with anything Microsoft provides. When something similar is introduced to Azure, why keep the subsidiary's internal competition around? This happened already with VS Code vs. Github's Atom editor whose development has ceased earlier this year. (Not that I ever was a huge fan of Atom, but its discontinuation is a direct result of the Microsoft acquisition.)
Also, GitHub Actions is based on Azure Pipelines already.
I have spent the last two days fighting with these new Github tools. I've been trying to do a simple Hello-World Maven app, built on Github Actions and deployed to Github Packages. It does not work. Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete. They have short little articles on how to do things, and for each…
For my Java project, I set up GitHub Packages as a server in my settings.xml, and then use:
mvn deploy -Dgithub.username=${{github.actor}} -Dgithub.password=${{github.token}} -s settings.xml
as a step in my GitHub Actions workflow.
I'm not super familiar with maven, so I'll talk with the Packages team about how we can improve the documentation here.
I had to setup CI for a GitHub open source project recently, and decided to give GitHub Actions a try. I have to say it's pretty nice to have the CI directly handled by GH (GitLab has been doing it for years, I know...). I hope it's gonna help some open source projects to easily add CI validations to their PR workflow. That being said, there was only Ubuntu images for the Linux builds, and I'm not aware of a way to r…
Most of the Actions are actually custom containers. So to run your own code you can just make an action, which isn't that complex.
Actions themselves are meant to support the workflow and distill a set of complex steps into something that can be done in a single workflow command. (For example, download and set up a new version of a Java JDK.) They're meant to be used as steps in many peoples workflows, instead of executing a single workflow.
The actions themselves can be built as either a container, which is self-contained, or as JavaScript. I often recommend the latter, since that will work cross platform (containers only work for people who are using workflows running on Linux).
I have spent the last two days fighting with these new Github tools. I've been trying to do a simple Hello-World Maven app, built on Github Actions and deployed to Github Packages. It does not work. Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete. They have short little articles on how to do things, and for each…
Agreed. A lot of times they seemed to use the ole "make a blog post about X and we'll call it documentation" strategy that a lot of others seem to be employing as well. The net result is useless documentation that is often outdated by the time a product is live. However, that doesn't change the fact that it's still the top search engine result for the topic or the de facto page many link to within their own actual 'documentation'.