- Last 7 days
-
documents.craft.me documents.craft.me
-
new option to restore the last closed tab using CMD + Shift + T
Tags
Annotators
URL
-
- Feb 2024
-
github.com github.com
-
even though Hash.ruby2_keywords_hash?(args.last) returns true. 🤯 And this statement (from #366): # If the last argument is Hash, Ruby will treat only symbol keys as keyword arguments # the rest will be grouped in another Hash and passed as positional argument. doesn't seem to be correct, at least in Ruby 3.0.
-
- Jan 2024
-
-
Document what to build and how designs should behave in a central, searchable, collaborative place for the entire product team.
Tags
Annotators
URL
-
- Dec 2023
-
diataxis.fr diataxis.fr
-
diataxis.fr diataxis.fr
-
Diátaxis is the work of Daniele Procida.
See also: https://documentation.divio.com/
Tags
Annotators
URL
-
-
er4hn.info er4hn.info
-
er4hn.info er4hn.info
-
I think Peter called this "secret knowledge".
-
- Nov 2023
-
documentation.divio.com documentation.divio.com
-
docsify.js.org docsify.js.orgDeploy1
-
A magical documentation site generator. Simple and lightweightNo statically built html filesMultiple themes
-
- Oct 2023
-
-
International Conference on Indigenous Language Documentation, Education and Revitalization (ICILDER) last weekend at the University of Indiana.
-
- Sep 2023
-
www.apple.com www.apple.com
-
I think it is absolutely absurd that Apple still(?) chooses to publish "complete" ""feature lists"" in Portable Document Format, of all motherfucking things, but - as always - thank fucking God for mr Hypo Thesis over here!
-
- Aug 2023
-
support.apple.com support.apple.com
-
If there’s only an asterisk: Click the style name, then move the pointer over the style name in the Paragraph Styles pop-up menu. Click the arrow that appears, then choose Redefine from Selection.
Pages is so much more impressive than you'd expect in so many ways, but damn...
The way styles are handled still perplexes the shit out of me... even after consuming this document.
-
- Jul 2023
-
queue.acm.org queue.acm.org
-
Tell future-you why you did that thing; they can read but don't know what you intended. Oral tradition is like never writing state to disk; flush those buffers.
Tags
Annotators
URL
-
- Jun 2023
-
vadimkravcenko.com vadimkravcenko.com
-
A documentation-first culture does not mean everyone is busy writing documents all day. It means that everyone appreciates the value of documenting and sharing their experiences.
Documentation-first culture
-
I’m a big fan of documentation. I think it’s my favorite boring thing to do after coding. It brings the business so much long-term value that every hour invested into documentation by anyone saves literally x100 productivity hours across the company.
High five :)!
-
- May 2023
-
ocaml.github.io ocaml.github.io
-
Available as a monolithic file, by chapters, and in PDF — git repository.
What a cool documentation design; I love the all-in-one layout.
Very reminiscent of the old CoffeeScript docs, to me.
Tags
Annotators
URL
-
-
www.macstories.net www.macstories.net
-
Mona also makes good use of the iPad’s support for keyboard shortcuts.
See my reference Craft document for an index of said shortcuts. (I intend to publish it in more formats soon.)
-
- Apr 2023
-
club.macstories.net club.macstories.net
-
Raindrop also has an excellent browser extension that allows you to save a webpage to any of your link collections, tag it, mark it as a favorite, access highlights, set reminders, and even save multiple tabs simultaneously.
Which can be triggered by perhaps the most reliable Safari Extension keyboard shortcut (on iOS/iPadOS) to date:
⌘⇧E
.
-
-
support.apple.com support.apple.com
-
You can also send it to another person to share it with them.
Kindof astonished Apple acknowledged this, here.
-
-
docs.asciidoctor.org docs.asciidoctor.org
-
asciidoc.org asciidoc.org
Tags
Annotators
URL
-
- Mar 2023
-
www.wired.com www.wired.com
-
Profile of Ted Nelson
-
- Jan 2023
-
s3.amazonaws.com s3.amazonaws.com
-
https://s3.amazonaws.com/plan9-bell-labs/7thEdMan/index.html<br /> Unix Seventh Edition Manual
<small><cite class='h-cite via'>ᔥ <span class='p-author h-card'>Brandon Rhodes</span> in Semantic Linefeeds (<time class='dt-published'>12/27/2022 11:35:19</time>)</cite></small>
-
- Nov 2022
-
webmonetization.org webmonetization.org
-
Web Monetization
Web Monetization official site with motivation, wallets, providers, browsers, search engines, tools, documentation link, explainer link, specifications link, awesome list link, github link
Tags
- puma
- coil
- gridsome
- monetization
- plugin
- tessy
- donations
- micro-payment
- gatsby
- jekyll
- hugo
- pipe web
- web monetization
- ngx
- javasript
- github
- motivation
- list
- standard
- mozilla
- mojeek
- vuepress
- gatehub
- moodle
- svelte
- protocol
- revenue
- chrome
- w3c
- wallet
- ledger
- documentation
- interledger
- infinity search
- specification
- 11ty
- currency
- ilp
- money
- edge
- uphold
- explainer
- awesome
Annotators
URL
-
-
github.com github.com
-
It would probably be worth mentioning this explicitly in the README: "Configuration of the language server happens over the LSP protocol by passing a configuration object; your LSP client should have a way of setting the configuration object for a server. Here is a link to the spec for the configuration that is supported [...]"
-
-
thomasmdickinson.github.io thomasmdickinson.github.io
-
https://thomasmdickinson.github.io/lab-soc-about/
<small><cite class='h-cite via'>ᔥ <span class='p-author h-card'>Keeper of the Labyrinth </span> in Keeper of the Labyrinth: "#Mastodon #Hometown #Admin I love documentation…" - Labyrinth.Social (<time class='dt-published'>11/19/2022 01:31:45</time>)</cite></small>
In putting it together, I looked at a lot of other instances to see what kind of docs and policies they had, so now I want to pay it forward and put it out there for others to use as a basis.
If you run a small instance or are thinking of doing so, feel free to repurpose what I've put together!
-
-
plantuml.com plantuml.com
-
www.oscarberg.com www.oscarberg.com
-
And with diagrams as text close to the code chances are they will be kept to up to date (and created to begin with…).
-
-
raphael-leger.medium.com raphael-leger.medium.com
-
It is handy to manually generate the diagram from times to times using the previously created command: npm run db:diagram:generate. Though, getting the diagram to update itself on its own automatically without a developer interaction would ensure that it the diagram is never obsolete. There are several ways of doing this.You could use a pre-commit git hook or even better simply configure your CI/CD pipeline(s) to run the npm script whenever something gets merged into the main branch 🙂
-
When it comes to showing up somewhere in your documentation a diagram describing your SQL database, you often end up with a recurring problem : after a few days / weeks / months, the diagram you made became obsolete.
-
-
www.autohotkey.com www.autohotkey.com
-
Testing if Google Chrome can make annotations on this Auto Hotkey documentation page.
It (and Brave) can't make highlights or annotations for some reason. The prompt doesn't appear when text is highlighted, why is this? Is there a way to force the prompt to appear?
-
Page: Escape Sequences
I was looking for documentation on escaped characters.
This was because Auto Hotkey threw an error when I used
<%* %>
as an option for the text insert script. It said the illegal character was*
but really what was happening was that the unquoted text%* %
was treated like a variable since%
is used to enclose variables in Auto Hotkey. The solution was to escape the percent sign with one left back tick.
-
-
silentvoid13.github.io silentvoid13.github.io
-
Page on the the Templater syntax
<%+ ... %>
. It allows use of "dynamic commands" which are only executed in preview mode in Obsidian
-
-
h.readthedocs.io h.readthedocs.io
-
the functional core, imperative shell pattern
Link to video on "Boundaries" doesn't go into depth on the functional core, imperative shell pattern. However, this one does: https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell
-
For new code, it’s usually a good idea to design the code so that it’s easy to test with “real” objects, rather than stubs or mocks.
-
We keep our functional tests separate from our unit tests, in the tests/functional directory. Because these are slow to run, we will usually write one or two functional tests to check a new feature works in the common case, and unit tests for all the other cases.
Keep functional & unit tests separate. Functional for common cases, unit for all others.
-
To run the backend test suite only call tox directly
Probably means, "Call
tox
directly if you only want to run the backend test suite."
-
- Oct 2022
-
www.sumologic.com www.sumologic.com
-
will improve collaboration
The article contains no proof of this statement.
If someone knows of research that proves this, please let me know.
-
-
fairmat-experimental.github.io fairmat-experimental.github.io
-
information
generic example of that the concept of an error should be attached to the quantity or a field with <same_name>_error should be added
-
-
github.com github.com
-
Our most current documentation to get started with Aruba as a user can be found in ./features/.
-
-
roadturtlegames.com roadturtlegames.com
-
Impact Object – The Impact Object collision data will be sent to. If empty, it will attempt to find an Impact Object on the collider that was hit or one of its parents.
? What does it mean for a collision data to be sent to an impact object?
In the other implementation, we used impact object rigidbody/single material and assigned to it the impact material we created, which would be used in the tags library.
? What are the details of the ImpactObjectRigidbody in this case?
-
Impact Triggers are components that tell Impact Objects when to play interactions and with what data. They are the origin that provides the data which is sent to the object’s Impact Material to ultimately play the interactions defined on the material.
-~
-
-
roadturtlegames.com roadturtlegames.com
-
Impact Object Rigidbody uses FixedUpdate to ensure accurate interactions, especially when sliding and rolling. However, this can cause overhead if there are a lot of objects.
^ It seems that FixedUpdate is prone to causing overhead
-
Any Impact Triggers must be on the root of the object (the same object as the Rigidbody), and should have their Impact Object field empty. Impact Triggers must be on the same component as the Rigidbody,
? Must be on the root of the object, the same object as the rigid body? which rigidbody, the parent or the child?
? Impact Triggers must be on the same component as the Rigidbody
-
Impact Object Single Material is the simplest type of Impact Object, with a single material used for the object. It is most suited for static objects and level geometry. You can add this script to your objects by going to
? what are static objects and level geometry?
-
Priority can be used to ensure that certain objects will always play their interactions, even if it requires "stealing" resources that are already in use.
~?
-
Impact Objects are components that you attach to the objects in your game’s world to specify their material, so that other objects (and other parts of your game) know how to interact with them. Impact Objects can also provide physics data such as rigidbody velocity.
^ Impact Objects can also provide physics data such as rigidbody velocity.
-
-
roadturtlegames.com roadturtlegames.com
-
The Audio Source Template prefab must have an Impact Audio Source component attached to it.
^ Creating an Audio Source Template as a singular source for audio management
-
Pool Size – The size of the object pool created for this audio source.
? What is an object pool?
-
-
roadturtlegames.com roadturtlegames.com
-
Impact Materials define what interactions will occur when an object interacts with the tags defined in the Impact Tag Library
-- the Impact Tag Library is where we define the list of tags for our materials.
i.e.: Plastic, Glass, Concrete...etc
-
-
roadturtlegames.com roadturtlegames.com
-
The size of this buffer limits the number of interaction results that can be returned by a single interaction, so make sure this is set appropriately for how many interaction results your materials can return.
~? What are interaction results?
Is it about how many times the object is interacted with in the scene?
How would one go on about measuring that?
-
This is a hard limit that will be checked as soon as a collision message is recieved. If the limit has been reached for that fixed update frame, processing will be aborted immediately. Typically you would want to set this to be about the same size as your object pools. Triggers can be set as High Priority to ignore this limit.
? what does it mean that processing will be aborted immediately? what is processing in that case?
Is it meant that the interactions; the sounds emitted would not go through if they were supposed to occur?
-
Material Mapping works best for static, single material objects. Without an Impact Object component attached, no material composition or velocity data can be obtained
~? Are static single material objects, objects without a rigid body?
? What does it mean for a material composition or velocity data to be obtained?
-
Material Mapping allows you to map Unity's Physics Materials to Impact Materials. This is useful so that you don't necessarily have to add an Impact Object component to all of the objects in your scene.
-~ The impact mapping would include the properties of the physics material by Unity and allows us to use Impact functionality, such as using the material to produce specific sounds on impact with it
-
For example, if you have a terrain you will probably want to set this to the number of textures your terrain uses.
Setting Material Composition Buffer Size to the number of textures the terrain uses
-
-
roadturtlegames.com roadturtlegames.com
-
The first field is an Impact Tag Library which is used to display a user-friendly dropdown for the tag or tag mask. The second field represents the actual value of the tag or tag Mask
-
Just remember that under the hood tags are represented only by integers, so using multiple tag libraries with different tag names does not mean you can have more than 32 tags.
Tags
-
-
docs.openvalidation.io docs.openvalidation.io
-
Rules formulated with openVALIDATION are thus at the same time a formal, machine-processable specification, but also a documentation that is easy for people to understand.
-
- Sep 2022
-
metalblueberry.github.io metalblueberry.github.io
-
Code explains what and how Documentation explains why.
-
So make sure to write your documentation, but do not explain your spells.
-
Do you really need those lines? Isn’t it clear enough? Well, I still find comments like this in a lot of cases and it gets funnier when the comment is obsolete and the code is doing other things. Following the example, let’s imagine that another developer adds support for PUT method. I think that this is what would happen.
-
-
-
That’s why it was such a life-changing event for me when I found Dash in 2012.
Offline docs: - macOS: Dash ($30) - Windows/Linux: Zeal (free) - Windows: [Velocity] (https://velocity.silverlakesoftware.com/) ($20) - Web: DevDocs
-
-
assetstore.unity.com assetstore.unity.com
-
To be fair, for a $30 asset I don't really expect that much support, but the problem here is that because of the lack of docs and hard to parse and modify codebase, folks are way more dependent on the developer than for other assets with proper docs, field tooltips, and maintainable code.
-
- Aug 2022
-
mermaid-js.github.io mermaid-js.github.io
-
Diagramming and documentation costs precious developer time and gets outdated quickly. But not having diagrams or docs ruins productivity and hurts organizational learning. Mermaid addresses this problem by enabling users to create easily modifiable diagrams, it can also be made part of production scripts (and other pieces of code).
-
-
-
try to provide duplicate overlapping examples.
Tags
Annotators
URL
-
-
github.com github.com
-
Thus my docs recommendation of public function beforeFilter(Event $event) // do not render out the now inconsistent one for is(json) if (!$this->request->is('jsonapi')) { throw new NotFoundException('Invalid access, use application/vnd.api+json for Content-Type and Accept.'); } } to specifically only whitelist the desired jsonapi for the general use case.
-
- Jul 2022
-
-
// NB: Since line terminators can be the multibyte CRLF sequence, care // must be taken to ensure we work for calls where `tokenPosition` is some // start minus 1, where that "start" is some line start itself.
I think this satisfies the threshold of "minimum viable publication". So write this up and reference it here.
Full impl.:
getLineStart(tokenPosition, anteTerminators = null) { if (tokenPosition > this._edge && tokenPosition != this.length) { throw new Error("random access too far out"); // XXX } // NB: Since line terminators can be the multibyte CRLF sequence, care // must be taken to ensure we work for calls where `tokenPosition` is some // start minus 1, where that "start" is some line start itself. for (let i = this._lineTerminators.length - 1; i >= 0; --i) { let current = this._lineTerminators[i]; if (tokenPosition >= current.position + current.content.length) { if (anteTerminators) { anteTerminators.push(...this._lineTerminators.slice(0, i)); } return current.position + current.content.length; } } return 0; }
(Inlined for posterity, since this comes from an uncommitted working directory.)
-
- Jun 2022
-
developer.apple.com developer.apple.com
-
No additional considerations for iOS, macOS, or tvOS.
Believe it or not, finding this sentence, just now was actually a huge breakthrough in my iPhone Keyboard Reference project...
Proud of you, bastards, for actually saying one sentence!
-
-
queue.acm.org queue.acm.org
-
Good documentation includes background and decision information that cannot be derived from the code.
Tags
Annotators
URL
-
- Apr 2022
-
documentation.divio.com documentation.divio.com
Tags
Annotators
URL
-
- Mar 2022
-
news.ycombinator.com news.ycombinator.com
-
I wish education was based around this principle.
This is a recurring grievance of mine with the way most people approach writing documentation. Closely related: code comments should explain the why, not the what (or worse the how—which just ends up rehashing the code itself).
Too many people try to launch right in and explain what they're doing—their solution to a problem—without ever adequately outlining the problem itself. This might seem like too much of a hassle for your readers, but often when the problem is explained well enough, people don't actually need to read your explanation of the solution.
Tags
Annotators
URL
-
- Feb 2022
-
www.techrepublic.com www.techrepublic.com
-
Don’t be the project people leave. Be the project people turn to.
Documentation is not about developers. Documentation is for the users, folks. There is no excuse - business or otherwise - for poor documentation. If your software is poorly documented, you have failed as a software company.
-
- Jan 2022
-
guides.lib.berkeley.edu guides.lib.berkeley.edu
- Dec 2021
-
canvas.rocks canvas.rocks
-
- Nov 2021
-
help.twitter.com help.twitter.com
-
In addition to the daily limits, there are follow ratios that go into effect once you’re following a certain number of accounts:Every Twitter account can follow up to 5,000 accounts. Once you reach that number, you may need to wait until your account has more followers before you can follow additional accounts. This number is different for each account and is automatically calculated based on your unique ratio of followers to following.
Hello. I am a paying subscriber, now, after all these years… I may or may not have become a paying subscriber just to justify this particular feedback after all this time.
Ultimately, though, I’m giving you a real substantial bullet point to put on that very wispy-looking full features list of Twitter Blue!
-
- Sep 2021
-
futureofcoding.org futureofcoding.org
-
Around 1:48:00
What if every library that you use had, like, some interactive documentation or interactive representation? [...] The author could maybe add annotations.
-
- Aug 2021
-
github.com github.com
-
I hope you'll forgive me for defaulting to the documentation: I think it will do a better job of explaining it than me.
-
- Jul 2021
-
blog.appsignal.com blog.appsignal.com
-
the interesting thing here is that there are comments that say which concern depends on which.
-
-
icla2021.jonreeve.com icla2021.jonreeve.com
-
I have made some discoveries in London about my uncle Herncastle and his Diamond, which have rather an ugly look to my eyes; and I want you to confirm them.
Evidence of what Mr Franklin about information about the story.
-
This prefatory narrative I have already got by me in the form of an old family paper, which relates the necessary particulars on the authority of an eye-witness
State the evidentiary insistence.
-
- Jun 2021
-
github.com github.com
-
Most of the matchers provided by this gem are useful in a Rails context, and as such, can be used for different parts of a Rails app: database models backed by ActiveRecord non-database models, form objects, etc. backed by ActiveModel controllers routes (RSpec only) Rails-specific features like delegate
-
-
www.migrationencounters.org www.migrationencounters.org
-
So that was our rainbow child, Eli, and that's when I started going downhill, because my stuff got denied. I didn't have the privileges that every normal US citizen gets to have. So I had two kids, no way to provide for them.
Time in US - employment - documentation
-
No, they haven't reached an agreement, but it's this new dream. If you had known that all you had to do was keep going to school and you could get a social security card and you could have a path to citizenship, would that have made a difference, do you think?
DACA - Eligibility
-
We didn't have papers. On top of that, we're not from there. So we don't have papers. Not papers, but you know how you have to get the medical shots. We had to redo all of that stuff. So my mom got the shots, did all the immunization records and all that stuff.
Time in US - immigration status - being secretive - in the shadows - healthcare
-
I noticed all my friends getting jobs and having new shoes and this and that. And I would ask him like, "What are you doing?" And he was like, "I just got a job. I got a car. I got this."Mike: I could see them--that they were advancing in life, and I was still in the same spot. So I asked my mom if I could get a job, and that's when she broke it down to me that I wasn't even from here. And that was right there like a slap in the face.
Time in the US, Jobs/ Employment/ Work, Documents
-
-
www.migrationencounters.org www.migrationencounters.org
-
Luisa: I was set to go into a good future. That's what it was, but when it came down to it, my mom was like, "No. You know what? You can't. You don't have papers. You can't continue your education here. We cannot afford to pay your entire tuition. We cannot afford to pay for your housing or your books. Each book, that's like $5000 for books. We can't do that. I'm sorry."
Time in the US, Higher Education, Paying For
-
The first time was when I wanted to apply to Whitney Young—when I wanted to go to a different high school. I had the grades for it [Chuckles]. I've always had the grades for it, but they were asking … I don't remember what kind of document they were asking for that scared me into not applying, and I was like, "You know what? Let’s not. I don't want to. It's not worth it if I get deported. I don't need to be—it's not necessary." So I went to my local high school, which … not the best high school, Washington High School, but they had the IB program.
Time in the US, School, High School
-
Yes. There came a point. We were in the [Pause] process of getting our permanent residency card in order to be able to go to school, and the lawyer let my mother know that me and my sister—my other sister—were not going to make it because once you hit eighteen, you're no longer under the case that you originally filed, so the best option for us would be adoption. We would be adopted by an American citizen in order to get our American status fixed, and that was something my mom and I contemplated for a long, long time, and she was going to go through with it, but my dad put a huge stop to that and was like, "That's not happening. You're stupid. That's not a thing. These are my kids. You're not letting that happen."
Eligibility - permanent residency - adoption
-
-
developer.mozilla.org developer.mozilla.org
-
A cookie is associated with a domain. If this domain is the same as the domain of the page you are on, the cookie is called a first-party cookie. If the domain is different, it is a third-party cookie. While the server hosting a web page sets first-party cookies, the page may contain images or other components stored on servers in other domains (for example, ad banners), which may set third-party cookies. These are mainly used for advertising and tracking across the web.
-
-
developer.mozilla.org developer.mozilla.org
-
www.apollographql.com www.apollographql.com
-
docs.gitlab.com docs.gitlab.com
- Apr 2021
-
writefreely.org writefreely.org
-
Javascript
"JavaScript" (or "JS")
Tags
Annotators
URL
-
-
developers.write.as developers.write.as
-
Javascript
"JavaScript" (or "JS")
Tags
Annotators
URL
-
-
writefreely.org writefreely.org
-
```go package main import “fmt” func main() { fmt.Println(“Hello, world”) }
gaps between lines is off here.
-
```go
No close fence?
-
-
writefreely.org writefreely.org
-
Need to eliminate the overlap between this page and the Development Setup page.
Tags
Annotators
URL
-
-
writefreely.org writefreely.org
-
–
Should be U+2014
-
Be as specific or vague as you'd like – it is your blog
This should be an em dash (U+2014). Here, it is an en dash (U+2013).
-
-
writefreely.org writefreely.org
-
one more
"one"?
-
-g
bad hygiene; unnecessary
-
install LESS compiler
This step prompts me for superuser privileges (it shouldn't; probably installing lessc as a global utility (it shouldn't)) and then still fails.
-
Need to eliminate the overlap between this page and the Getting Started page.
-
-
gist.github.com gist.github.com
-
I'm maintaining one that can be run and asserted on: https://github.com/cirosantilli/rails-cheat/blob/master/app/test/integration/capybara_test.rb
-
- Mar 2021
-
www.forbes.com www.forbes.com
-
The urgent argument for turning any company into a software company is the growing availability of data, both inside and outside the enterprise. Specifically, the implications of so-called “big data”—the aggregation and analysis of massive data sets, especially mobile
Every company is described by a set of data, financial and other operational metrics, next to message exchange and paper documents. What else we find that contributes to the simulacrum of an economic narrative will undeniably be constrained by the constitutive forces of its source data.
-
-
api.rubyonrails.org api.rubyonrails.org
-
Third configurable block to run.
I like how they identify in the description which order things run in: 1st, 2nd, 3rd, and last.
Though, it would be more readable to have a list of them, in chronological order, rather than having them listed in alphabetical order.
-
-
github.com github.com
-
github.com github.com
-
Sprockets 4: The effect of config.assets.debug does not match the rails documentation.
-
This appears to be an undocumented breaking change. For example, the word "debug" does not appear in the sprockets 4 changelog.
-
Should it only contain link* calls?
-
-
The docs say: "When using Rails and Sprockets in development mode, no assets are concatenated."
Tags
- no longer the case (outdated info)
- issues: for improving documentation
- sprockets
- undocumented change (missing from changelog)
- breaking change
- I noticed this too
- documentation: inaccurate/outdated
- issues: for first impressions / beginner trouble
- issues: excellent
- how do you know if you are doing it correctly? (need better feedback/discoverability)
- I have this problem too
- need better documentation
Annotators
URL
-
-
bilge.world bilge.world
-
demonstrate
I’ve continued to discover new features in Tweetbot for the first time, believe it or not. .
-
Page Note Test Not quite sure why I haven't tried Page Notes yet but...
- The GitHub Issue for this review
Tags
Annotators
URL
-
-
github.com github.com
-
github.com github.com
-
First sighting (type: mention/link): https://hyp.is/3AMkJHumEeurpAsw_sA3nA/trailblazer.to/2.1/blog.html
Example that uses it: https://github.com/trailblazer/tutorial/blob/master/ruby/test/basics_test.rb
-
-
trailblazer.to trailblazer.to
-
we have a helpful little framework behind the page rendering that pulls code snippets from real tests out of the actual gems
-
Writing documentation for the new website has been fun. Yes, fun!
-
We have fully documented the migration path to 2.1 while upgrading several complex apps. It worked.
-
-
trailblazer.to trailblazer.to
-
Advanced features like tracing, input/output filters or type checking leverage the framework argument flow_options
Tags
Annotators
URL
-
- Feb 2021
-
trailblazer.to trailblazer.to
-
What this means is: I better refrain from writing a new book and we rather focus on more and better docs.
I'm glad. I didn't like that the book (which is essentially a form of documentation/tutorial) was proprietary.
I think it's better to make documentation and tutorials be community-driven free content
-
We try to keep the “information architecture” - a word I wouldn’t have learned without the inspiring Alex Coles - as simple as possible: so far, we got a handful of pages accessible through the top navigation, and then the documentation behind the DOCS link. Here, the right sidebar helps you to navigate within the chapter.
-
-
github.com github.com
-
Use the desc option to provide human-readable descriptions of filters. You should prefer these to comments because they can be used to generate documentation.
-
-
nixos.org nixos.org
-
NIX_PATHA colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (i.e., <path>). For instance, the value
It would be helpful to
- formally describe the formats for NIXPATH, and
- note the allowed angle bracket syntax accordingly
<path>
will work with the prefixless format, but not with the prefixed one, and it may be helpful to spell this out explicitly.0 [14:16:19] nix repl Welcome to Nix version 2.3.10. Type :? for help. nix-repl> :l <nixpkgs/doc> Added 40 variables. nix-repl> :l <doc> error: file 'doc' was not found in the Nix search path (add it using $NIX_PATH or -I)
I always saw a NIXPATH used with the prefix syntax so far:
$ echo $NIX_PATH nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixos:nixos-config=/etc/nixos/configuration.nix:/nix/var/nix/profiles/per-user/root
but
NIX_PATH
documentation shows that the prefixless format is also valid.$ export NIX_PATH=/home/toraritte:/nix/var/nix/profiles/per-user/root/channels/nixos $ printenv NIX_PATH /home/toraritte:/nix/var/nix/profiles/per-user/root/channels/nixos $ nix repl Welcome to Nix version 2.3.10. Type :? for help. nix-repl> :l <nixpkgs> Added 12439 variables.
Tags
Annotators
URL
-
-
10.11.66.200 10.11.66.200
-
1-650-649-1942
-
estateclaims@my.usdirectexpress.com
-
1-650-649-1942
-
docs@my.usdirectexpress.com
-
- Jan 2021
-
nintil.com nintil.com
-
every document could disappear 6 months after it's published unless whoever uploaded or created it says otherwise in an email the system sends them after six months, documents shouldn't live rent free
this is a great idea to ensure that documentation doesn't become stale.
-
-
www.freedesktop.org www.freedesktop.org
-
Reload the systemd manager configuration. This will rerun all generators (see systemd.generator(7)), reload all unit files, and recreate the entire dependency tree. While the daemon is being reloaded, all sockets systemd listens on behalf of user configuration will stay accessible.
-
- Nov 2020
-
typedoc.org typedoc.orgHome1
Tags
Annotators
URL
-
-
material-components.github.io material-components.github.io
- Oct 2020
-
docs.arc42.org docs.arc42.org
-
github.com github.com
-
-
we do need to have this somewhere
-
-
-
I'm afraid there's only so much the docs & tutorials can do about something like this actually. When you first read them, you don't get Svelte well enough (since you're reading a tutorial...) for this to make sense to you. Then you try something, encounter a behaviour, question it, understand better... That's learning.
-
Anyway, If this is an expected behaviour, we should probably add an asterisk to the docs, describing the pitfall, because I believe many will be bitten by this.
-
-
vuejs.org vuejs.org
-
These are good docs.
Referenced by: https://github.com/sveltejs/svelte/issues/3368#issuecomment-519289238
-
-
github.com github.com
-
Would you mind adding it to the vendor README.md with a note to this commit so we remember?
-
-
github.com github.com
-
-
More in-depth examples definitely sound like a good idea. I've seen cookbooks quite a few times already and they are always helpful.
-
-
github.com github.com
-
They even named the main file
react.js
so when converting/migrating components from React you could (at least some of the time, perhaps) simply leave some of the imports as-is:import {createHooks, useRef} from './react';
-
-
github.com github.com
-
Only peer dependencies: Svelte and Final Form
-
-
stackoverflow.blog stackoverflow.blog
-
In an effort to rethink how documentation works, we recently introduced Articles, longer-form prose that can sit side by side with shorter Q&A.
-
- Sep 2020
-
github.com github.com
-
I don't read comments as I think they are dangerous
Why does he think they are dangerous?
-
-
stackoverflow.com stackoverflow.com
-
I really have no idea how you came up with this solution but that reflects a major problem with many npm packages, i.e. 90 percent of the library documentation should be pulled from the Git issues or SO answers.
-
-
elemental.medium.com elemental.medium.com
-
Austin S. (2020) This Lawyer Ran Errands for His High-Risk Wife. Then an Epidemiologist Rated His Every Move.https://elemental.medium.com/this-lawyer-ran-errands-for-his-high-risk-wife-then-an-epidemiologist-rated-his-every-move-f9a926ad96ec
-
-
github.com github.com
-
To add documentation on a Svelte component that will show up as a docstring in LSP-compatible editors, you can use an HTML comment with the @component tag:
-
- Aug 2020
-
github.com github.com
-
All of the components should allow passing MUI configuration properties to them so that they can be easily customized. In the case of RFF and MUI components with deeply nested structures of multiple subcomponents, you can pass the properties in with sepecial top level properties. This is very hard to document fully without making a mess, so please refer to the source code and demos for examples.
-
- Jul 2020
-
github.com github.com
- Jun 2020
-
docs.gitlab.com docs.gitlab.com
- May 2020
-
docs.gitlab.com docs.gitlab.com
Tags
Annotators
URL
-
-
thoughtbot.com thoughtbot.com
-
www.elegantthemes.com www.elegantthemes.com
-
about.gitlab.com about.gitlab.com
-
If we find that GitLab doesn't work as people expect, the documentation should be updated so this is no longer a surprise. This applies whether we classify it as a feature request or a bug.
-
-
developer.mozilla.org developer.mozilla.org
- Apr 2020
-
realpython.com realpython.com
-
Sometimes, the best way to learn is to mimic others. Here are some great examples of projects that use documentation well:
Examples of projects that use documentation well
(chech the list below)
-
“Code is more often read than written.” — Guido van Rossum
-
Documenting code is describing its use and functionality to your users. While it may be helpful in the development process, the main intended audience is the users.
Documenting code:
- describing use to your users (main audience)
-
Class method docstrings should contain the following: A brief description of what the method is and what it’s used for Any arguments (both required and optional) that are passed including keyword arguments Label any arguments that are considered optional or have a default value Any side effects that occur when executing the method Any exceptions that are raised Any restrictions on when the method can be called
Class method should contain:
- brief description
- arguments
- label on default/optional arguments
- side effects description
- raised exceptions
- restrictions on when the method can be called
(check example below)
-
Comments to your code should be kept brief and focused. Avoid using long comments when possible. Additionally, you should use the following four essential rules as suggested by Jeff Atwood:
Comments should be as concise as possible. Moreover, you should follow 4 rules of Jeff Atwood:
- Keep comments close to the code being described.
- Don't use complex formatting (such as tables).
- Don't comment obvious things.
- Design code in a way it comments itself.
-
From examining the type hinting, you can immediately tell that the function expects the input name to be of a type str, or string. You can also tell that the expected output of the function will be of a type str, or string, as well.
Type hinting introduced in Python 3.5 extends 4 rules of Jeff Atwood and comments the code itself, such as this example:
def hello_name(name: str) -> str: return(f"Hello {name}")
- user knows that the code expects input of type
str
- the same about output
- user knows that the code expects input of type
-
Docstrings can be further broken up into three major categories: Class Docstrings: Class and class methods Package and Module Docstrings: Package, modules, and functions Script Docstrings: Script and functions
3 main categories of docstrings
-
According to PEP 8, comments should have a maximum length of 72 characters.
If
comment_size
> 72 characters:use `multiple line comment`
-
Docstring conventions are described within PEP 257. Their purpose is to provide your users with a brief overview of the object.
Docstring conventions
-
All multi-lined docstrings have the following parts: A one-line summary line A blank line proceeding the summary Any further elaboration for the docstring Another blank line
Multi-line docstring example:
"""This is the summary line This is the further elaboration of the docstring. Within this section, you can elaborate further on details as appropriate for the situation. Notice that the summary and the elaboration is separated by a blank new line. # Notice the blank line above. Code should continue on this line.
-
say_hello.__doc__ = "A simple function that says hello... Richie style"
Example of using
__doc
:Code (version 1):
def say_hello(name): print(f"Hello {name}, is it me you're looking for?") say_hello.__doc__ = "A simple function that says hello... Richie style"
Code (alternative version):
def say_hello(name): """A simple function that says hello... Richie style""" print(f"Hello {name}, is it me you're looking for?")
Input:
>>> help(say_hello)
Returns:
Help on function say_hello in module __main__: say_hello(name) A simple function that says hello... Richie style
-
class constructor parameters should be documented within the __init__ class method docstring
init
-
Scripts are considered to be single file executables run from the console. Docstrings for scripts are placed at the top of the file and should be documented well enough for users to be able to have a sufficient understanding of how to use the script.
Docstrings in scripts
-
Documenting your code, especially large projects, can be daunting. Thankfully there are some tools out and references to get you started
You can always facilitate documentation with tools.
(check the table below)
-
Commenting your code serves multiple purposes
Multiple purposes of commenting:
- planning and reviewing code - setting up a code template
- code description
- algorithmic description - for example, explaining the work of an algorithm or the reason of its choice
- tagging -
BUG
,FIXME
,TODO
-
In general, commenting is describing your code to/for developers. The intended main audience is the maintainers and developers of the Python code. In conjunction with well-written code, comments help to guide the reader to better understand your code and its purpose and design
Commenting code:
- describing code to/for developers
- help to guide the reader to better understand your code, its purpose/design
-
Along with these tools, there are some additional tutorials, videos, and articles that can be useful when you are documenting your project
Recommended videos to start documenting
(check the list below)
-
If you use argparse, then you can omit parameter-specific documentation, assuming it’s correctly been documented within the help parameter of the argparser.parser.add_argument function. It is recommended to use the __doc__ for the description parameter within argparse.ArgumentParser’s constructor.
argparse
-
There are specific docstrings formats that can be used to help docstring parsers and users have a familiar and known format.
Different docstring formats:
- Google docstrings (not a formal specification)
- reStructured Text
- NumPy/SciPy docstrings
- Epytext
-
Daniele Procida gave a wonderful PyCon 2017 talk and subsequent blog post about documenting Python projects. He mentions that all projects should have the following four major sections to help you focus your work:
Public and Open Source Python projects should have the
docs
folder, and inside of it:- Tutorials
- How-To Guides
- References
- Explanations
(check the table below for a summary)
-
Since everything in Python is an object, you can examine the directory of the object using the dir() command
dir() function examines directory of Python objects. For example
dir(str)
.Inside
dir(str)
you can find interesting property__doc__
-
Documenting your Python code is all centered on docstrings. These are built-in strings that, when configured correctly, can help your users and yourself with your project’s documentation.
Docstrings - built-in strings that help with documentation
-
Along with docstrings, Python also has the built-in function help() that prints out the objects docstring to the console.
help() function.
After typing
help(str)
it will return all the info about str object -
The general layout of the project and its documentation should be as follows:
project_root/ │ ├── project/ # Project source code ├── docs/ ├── README ├── HOW_TO_CONTRIBUTE ├── CODE_OF_CONDUCT ├── examples.py
(private, shared or open sourced)
-
In all cases, the docstrings should use the triple-double quote (""") string format.
Think only about """ when using docstrings
-
-
-
TSDoc is a way of writing TypeScript comments where they’re linked to a particular function, class or method (like Python docstrings).
-
-
github.com github.com
-
developers.google.com developers.google.com
-
www.youtube.com www.youtube.com
-
mkdocs for diagrams seems cool. :)
-
Tags
Annotators
URL
-
-
docs.opencv.org docs.opencv.org
-
Installation in Windows Compatibility: > OpenCV 2.0 Author: Bernát Gábor You will learn how to setup OpenCV in your Windows Operating System!
-
-
opencv.org opencv.orgAbout1
-
OpenCV (Open Source Computer Vision Library) is an open source computer vision and machine learning software library. OpenCV was built to provide a common infrastructure for computer vision applications and to accelerate the use of machine perception in the commercial products. Being a BSD-licensed product, OpenCV makes it easy for businesses to utilize and modify the code. The library has more than 2500 optimized algorithms, which includes a comprehensive set of both classic and state-of-the-art computer vision and machine learning algorithms. These algorithms can be used to detect and recognize faces, identify objects, classify human actions in videos, track camera movements, track moving objects, extract 3D models of objects, produce 3D point clouds from stereo cameras, stitch images together to produce a high resolution image of an entire scene, find similar images from an image database, remove red eyes from images taken using flash, follow eye movements, recognize scenery and establish markers to overlay it with augmented reality, etc. OpenCV has more than 47 thousand people of user community and estimated number of downloads exceeding 18 million. The library is used extensively in companies, research groups and by governmental bodies. Along with well-established companies like Google, Yahoo, Microsoft, Intel, IBM, Sony, Honda, Toyota that employ the library, there are many startups such as Applied Minds, VideoSurf, and Zeitera, that make extensive use of OpenCV. OpenCV’s deployed uses span the range from stitching streetview images together, detecting intrusions in surveillance video in Israel, monitoring mine equipment in China, helping robots navigate and pick up objects at Willow Garage, detection of swimming pool drowning accidents in Europe, running interactive art in Spain and New York, checking runways for debris in Turkey, inspecting labels on products in factories around the world on to rapid face detection in Japan. It has C++, Python, Java and MATLAB interfaces and supports Windows, Linux, Android and Mac OS. OpenCV leans mostly towards real-time vision applications and takes advantage of MMX and SSE instructions when available. A full-featured CUDAand OpenCL interfaces are being actively developed right now. There are over 500 algorithms and about 10 times as many functions that compose or support those algorithms. OpenCV is written natively in C++ and has a templated interface that works seamlessly with STL containers.
Tags
Annotators
URL
-
-
tesseract-ocr.github.io tesseract-ocr.github.io
-
tessdoc Tesseract documentation
-
-
falcon.readthedocs.io falcon.readthedocs.io
-
“The source code for Falcon is so good, I almost prefer it to documentation. It basically can’t be wrong.”
-