Those one line snippets are likely going to be taken down, most systems are too complicated for those to work. It looks nice for a couple package systems but that Maven one is obviously flawed.
I'd be happy to help you dig through whatever you're trying to do; I'm @clarkbw on twitter. I'd also love another set of eyes on the changes to the setup-java action, specifically getting Maven authentication to work well.
https://github.com/actions/setup-java/pull/29
(I'm the PM heading up the Packages project at GitHub)
https://github.community/t5/How-to-use-Git-and-GitHub/Move-N...
It’s not just GitHub. There’s a language I (and the rest of HN) love that has adopted “story format” for documentation but is missing real, hard technical documentation apart from method-level codedocs. It’s nice for building momentum but it leaves you unable to find a central location with an architectural documentation of the system.
"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 different circumstances - so software usually needs them all."
I agreed with its premise — I've found things that only have "story format" docs (i.e. explanation / how-to guides) to be really frustrating. On the other hand, if all that's available is a deep and highly particular technical reference, it's really difficult to get started sometimes.
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
Writing documentation also seems to be a task you kick out to your junior developers that you'd rather not give more critical assignments to, which is backwards as can be.
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 of the box how to use your API. Like, what the heck. Just tell me how to talk to your API in simple terms. How hard is it?
"To use the CGP vision API there are two ways to authenticate and connect. 1) REST 2) SDKS" and then just explain to me how to do it simply.
Don't ramble like if this was the fucking Iliad. Go straight to the point and organize your information better.
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 have to often disregard the documentation and get into the gcloud (their Python-based CLI and API) to understand what the heck is going on and their CLI/API code is no good either. Layers and layers of abstraction in their code only to make some REST API calls. The amount of over-engineering and abstraction that is present in their Python code would put even Java SimpleBeanFactoryAwareAspectInstanceFactory developers to shame.
For example integrating support for Google Drive took months, where I ended up using a third party solution, and users are met with a big red warning about my app now being unknown. And the file system is laggy. Compared to integrating Dropbox which took three days and just works. Google Drive probably have thousands of pages of documentation. While Dropbox have one or two.
"This package is really good. Here is an example. This feature is cool! This other feature solves a common problem. Here is a list of some of the functions."
I haven't done any substantial Java work in probably 8 years and I still miss the JDK docs.
Concourse CI is the one I'm running up against this today - I'm taking over a partially built installation which has all sorts of hard-coded config environment variables that I'm trying to figure out their purpose.
Their documentation has basic getting-started stuff[1], but doesn't list all the config variables and their use. It's open source, so I cloned the repo, but they don't directly reference the environment variables there, either.
Compare that to, say, Ansible's documentation - it exhaustively lists all the options[2] and what they're used for, with links to other related documentation.
[1] https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices...
Our CLI hasn't really aged well and that's something I'd like to address soon - probably going more in the direction of config files instead of flags/env vars. It'd be a lot easier to document with a proper schema. Thanks for the feedback and sorry the experience is still pretty rocky!
Honestly the whole application seems pretty good - but everything is focussed on more hello-world stuff, which is great for getting going on my machine - not so great for running it for real.
Whether you use environment vars or a config file, I don't mind - one benefit environment vars gives is that setting CONCOURSE_BIND_IP to the instance's IP is relatively simple, eg on AWS:
CONCOURSE_BIND_IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)
If it's a config file then I need to update that before the application starts, which is more fiddling.
For a long time now we've been primarily focusing on the core design, concepts, and architecture at the expense of documentation and introductory material and outreach - we've never had a dedicated technical writer, so documentation is really best-effort. Now that the dust is settling on our roadmap I feel a lot more confident in increasing our focus on onboarding, operability, and developer/user experience in this coming year. :)
The TS docs basically just say "use declare to declare [thing]" over and over, and it's only mentioned in the handbook on a page that doesn't seem to be listed in the handbook menu anywhere.[0] You have to search for it and wing it, because the search result for this just says "By Example." Notice that there is no article highlighted in the handbook menu on the left like there would be on any of the pages listed there.
[0]: https://www.typescriptlang.org/docs/handbook/declaration-fil...
Maybe Rust or Clojure...?
I haven't really tried to do anything with Github Actions, I start looking at the docs and think, nah, not ready yet.
It does seem like a powerful tool.
It turns out that good docs is hard and "expensive", can't be handled as an afterthought without actually investing time/resources. A powerful complex tool that took a while to develop is gonna need a similar significant investment in docs.
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.
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'.
And that’s to watch a coworker who hasn’t used it before try to follow your docs. Try again, and then pick another coworker. By then it should be good enough for the majority to follow, and you take the rest of the questions as they come. Put the first draft out and you’ll be swamped with complaints.
But I do agree with you that it's very from from being an alternative, and instead should be used to supplement healthy documentation.
Given that you are using maven, which can be a bit fiddly, might it be the case that some of your issues are with your build? E.g. the way maven deploy works is very dependent on how you set up the pom file.
You can probably use another scripting language to use the github interface.
https://github.com/bbs-io/syncterm-windows
Aside, you need to pass your github token in as part of your workflow config.
https://github.com/bbs-io/syncterm-windows/blob/master/.gith...
There's also a lot of things you should be able to do but are not apparent or clear - and yeah the documentation is a disaster
Introspection is not valid in place of documentation.
When it comes to APIs if you're eschewing documentation it's because (I hope) you are trying to minimize support costs and thus devs using the API won't have someone to ask questions of so those edge cases become mysterious and assumptions are made that may be wrong.
If you're designing an API that serves up items that may be on sale how would you name fields so that the price and possibly sale discount are unambiguous to read?
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 sub-task they have a link to docs somewhere else. This would be fine, except the links don't point to anything useful.
To give an example: they say you can use the Github API to talk to Github Packages, but the link goes to their generic GraphQL documentation. They don't point to any reference material on the actual calls to the packages service. If it exists, I can't find it.
If you go to the main page in your account for Github Packages, it says that all you have to do is this:
mvn deploy -Dregistry=https://maven.pkg.github.com/mycompany -Dtoken=GH_TOKEN
That is just straight-out wrong. It does not work.
Seriously, Github, you need to fire your documentation team and hire some people who know how to write. Perhaps you should hire people who have actually used your tools to write the docs. Or just provide some freakin' working examples.