Items tagged with: documentation

Sooo, what are the prettiest online docs that you know and like? I'm partial to the style of the stripe/slack docs, but I'd like to see what other people like! #documentation
@Дима Ржевский
Если кому-то интересны детали нового протокола #Zot 6 который используется в грядущем релизе #Hubzilla 4.0, то за деталями прошу сюда.


#russian #lang ru #documentation
@Дима Ржевский
Если кому-то интересны детали нового протокола #Zot 6 который используется в грядущем релизе #Hubzilla 4.0, то за деталями прошу сюда.


#russian #lang ru #documentation

What nobody tells you about documentation

Daneiele Procida has given a speech about why good #documentation matters in your software. Watch the video at #peertube :

PeerTube: What nobody tells you about documentation (wat)

I think this just not applies on #Python exclusively but on all programming languages: document as much as you can.

Judicial Watch uncovers FBI's "chart of Hillary Clinton's potential violations"

#HillaryClinton committed so many #crimes, the #FBI could not figure out how to clear her of all of them without first constructing a #detailed #chart of them. Then they had to #cover-up the chart.

Government watchdog #JudicialWatch revealed Friday it has #obtained another 186 pages of #documentation from the #JusticeDepartment regarding #HillaryClinton’s #email-scandal, and they show #evidence of a #cover-up of an #FBI #chart of possible #violations by her.

“Judicial Watch caught the FBI in another cover-up to protect Hillary Clinton,” said the organization’s president, #TomFitton. “These records show that the FBI is hiding a chart detailing possible violations of the law by Hillary Clinton and the supposed reasons she was not prosecuted.”

Judicial Watch recently released hundreds of pages of #records showing former FBI #GeneralCounsel #JamesBaker discussed the #investigation of Clinton-related emails on #AnthonyWeiner’s #laptop with Clinton’s lawyer, #DavidKendall.

The latest cache of documents was obtained from the #government through a #Freedom-of-Information-Act #lawsuit filed against the Department of Justice after it failed to respond to a 2017 #FOIA request seeking all #communications between fired FBI official #PeterStrzok and his paramour, FBI lawyer #LisaPage.

It was #DistrictJudge Reggie B. Walton who ordered the #FBI to begin #processing some 13,000 pages of #records that fall under the order. Judicial Watch found, three days after then-FBI #Director #JamesComey’s press conference announcing that…

#DeepState #coverup #crime #crimes #Clintons #Hillary #Clinton #ClintonCrimeFamily
So I've started documenting everything I've done on my server to get it where it is...mainly because I've decided to start again from scratch when I eventually move to a dedicated server. The mail server section is long. Very long. Can't really publish it either at the mo as there's far too much plagiarism :) More for my own reference until I find the time to rewrite it all in my own words. It's basically many already existing tutorials merged together with a few tweaks where I've fixed things or implemented it slightly differently. It describes setting up postfix, dovecot, sieve, postfixadmin, along with securing it, strengthening it against spam, and integrating it with rspamd and clamav (with extra 3rd party signatures). All based on Ubuntu 18.04. I suspect that the next document I write describing MariaDB, PHP-FPM, Apache backend, Nginx reverse proxy, and Varnish is going to be longer still. Good job I find it interesting!

#vps #postfix #selfhosted #documentation

Show HN: DeskGap – Like Electron, but uses the system webview

 DeskGap is a framework for building cross-platform desktop apps with web technologies (JavaScript, HTML and CSS). To enable native capabilities while keeping the size down, DeskGap bundles a Node.js…

HN Discussion: https://news.ycombinator.com/item?id=19149690
Posted by patr0nus (karma: 110)
Post stats: Points: 155 - Comments: 76 - 2019-02-13T02:01:03Z

#HackerNews #but #deskgap #electron #like #show #system #the #uses #webview
Article content:



DeskGap is a framework for building cross-platform desktop apps with web technologies (JavaScript, HTML and CSS).

To enable native capabilities while keeping the size down, DeskGap bundles a [2]Node.js runtime and leaves the HTML rendering to the operating system‘s webview.

Supported Platforms[3]¶
* Mac OS X Yosemite (version 10.10) or later
 * Windows 10 October 2018 Update (version 1809) or later


Prebuilt Binaries[5]¶

npm install --save-dev deskgap

API Demos[6]¶

The DeskGap API Demos app shows some of the DeskGap features and APIs with interactive scripts.
macOS      Windows   Source Code

[7]Download [8]Download [9]GitHub

Pym: A Real-Life App Built With DeskGap[10]¶

To test DeskGap on field, [11]squoosh is wrapped into a desktop app "Pym" with DeskGap and submitted to the app stores.
macOS                         Windows             Source Code

[12]Download on Mac App Store [13]Download on Microsoft Store [14]GitHub

Getting Started[15]¶

Creating a Node.js Package for your app[16]¶

├── package.json
├── index.js
└── index.html

package.json points to the appʼs entry file and provides the script that starts your app:

{ "name": "hello-deskgap", "main": "index.js", "scripts": { "start": "deskgap ." }

index.js is the entry file that creates a window which will render a HTML page:

const { app, BrowserWindow } = require(ʼdeskgapʼ); app.once(ʼreadyʼ, () => { const win = new BrowserWindow(); win.loadFile(ʼindex.htmlʼ);

index.html is the page to render:

Hello DeskGap

Installing DeskGap[17]¶

npm install --save-dev deskgap

Starting Your App[18]¶


[20]Work in Progress


What’s the difference between DeskGap and [22]Electron?[23]¶

DeskGap is designed to be a more lightweight alternative to Electron. It does not bundle [24]Chromium or any other web engines. Instead, the ability of rendering HTML pages comes from the webview provided by the operating system, specifically, [25]WKWebView on macOS and [26]Microsoft.Toolkit.Forms.UI.Controls.WebView on Windows.

DeskGap is at its early stage. The API is still quite limited compared to Electron. Many functionalities are under development and some of them will probably never be possible. See [27]this and [28]this for more information.

There are already similar attempts ([29]electrino and [30]Quark for instance) out there. What makes DeskGap different?[31]¶

With a Node.js runtime bundled, DeskGap comes with support for npm packages and all the battle-tested native capabilities in Node.js such as [32]fs, [33]net, [34]http. The price is a larger executable size (about 8 MB zipped and 20 MB unzipped).

Why is the supported version of Windows so high? Any plan of supporting Windows 7 and Linux?[35]¶

Older Windows’ do not have a modern browser engine, only the one that powers Internet Explorer. Windows 10 1809 is the first version that provides a modern webview with [36]enough functionalities for DeskGap to be possible.

To support Windows 7, app developers would have to face compatibility issues coming from as low as IE 8. I personally don’t have enough motivation and interest to do this, but pull requests are always welcome.

Linux support would be great but I have little knowledge of Linux app development. For now I am looking at [37]Qt WebEngine. Any advice & help is appreciated.

If you want to try DeskGap but dropping Windows 7 (or Linux) support is a no-go for your app, consider packaging the app with Electron for the unsupported platform. The DeskGap API is intentionally designed to be like Electron’s. The following code is a good start:

let appEngine;
try { appEngine = require(ʼdeskgapʼ);
catch (e) { appEngine = require(ʼelectronʼ);
const { app, BrowserWindow } = appEngine;

So I can port my Electron app to DeskGap?[38]¶

Probably no. The DeskGap API is still quite limited. If you start building an app with DeskGap, getting it running on Electron may be easy, but not the other way around.


Visible links
1. https://github.com/patr0nus/DeskGap/edit/master/website/docs/index.md
2. https://nodejs.org/
3. https://deskgap.com/#supported-platforms
4. https://deskgap.com/#downloads
5. https://deskgap.com/#prebuilt-binaries
6. https://deskgap.com/#api-demos
7. https://deskgap.com/dl/macos
8. https://deskgap.com/dl/win32
9. https://github.com/patr0nus/DeskGap/tree/master/app
10. https://deskgap.com/#pym-a-real-life-app-built-with-deskgap
11. https://squoosh.app/
12. https://geo.itunes.apple.com/us/app/pym/id1451733095?mt=12&app=apps
13. https://www.microsoft.com/store/productId/9PMTMRNBXMPB
14. https://github.com/patr0nus/Pym
15. https://deskgap.com/#getting-started
16. https://deskgap.com/#creating-a-nodejs-package-for-your-app
17. https://deskgap.com/#installing-deskgap
18. https://deskgap.com/#starting-your-app
19. https://deskgap.com/#documentation
20. https://deskgap.com/api/
21. https://deskgap.com/#faq
22. https://electronjs.org/
23. https://deskgap.com/#whats-the-difference-between-deskgap-and-electron
24. https://www.chromium.org/
25. https://developer.apple.com/documentation/webkit/wkwebview
26. https://docs.microsoft.com/en-us/windows/communitytoolkit/controls/wpf-winforms/webview
27. https://deskgap.com/api/
28. https://deskgap.com/architecture/#synchronous-and-asynchronous-dispatching
29. https://github.com/pojala/electrino
30. https://github.com/jscherer92/Quark
31. https://deskgap.com/#there-are-already-similar-attempts-electrino-and-quark-for-instance-out-there-what-makes-deskgap-different
32. https://nodejs.org/api/fs.html
33. https://nodejs.org/api/net.html
34. https://nodejs.org/api/http.html
35. https://deskgap.com/#why-is-the-supported-version-of-windows-so-high-any-plan-of-supporting-windows-7-and-linux
36. https://docs.microsoft.com/en-us/microsoft-edge/dev-guide#win32-webview-updates
37. https://doc.qt.io/qt-5/qtwebengine-index.html
38. https://deskgap.com/#so-i-can-port-my-electron-app-to-deskgap

HackerNewsBot debug: Calculated post rank: 128 - Loop: 107 - Rank min: 100 - Author rank: 110
Outreachy provides three-month internships to work in Free and Open Source Software (FOSS). Interns are paid a stipend of $5,500 and have a $500 travel stipend available to them. Outreachy internship projects may include programming, user experience, documentation, illustration and graphical design, or data science. Interns often find employment after their internship with Outreachy sponsors or in jobs that use the skills they learned during their internship.
The application period for the May 2019 to August 2019 round will open in February.
Outreachy internships are open to applicants around the world. Interns work remotely with mentors from FOSS communities.
We expressly invite women (both cis and trans), trans men, and genderqueer people to apply. We also expressly invite applications from residents and nationals of the United States of any gender who are Black/African American, Hispanic/Latin@, Native American/American Indian, Alaska Native, Native Hawaiian, or Pacific Islander. Anyone who faces under-representation, systemic bias, or discrimination in the technology industry of their country is invited to apply.

#Outreachy #internship #FOSS #programming #documentation #graphical design #data science #women #cis #trans #men #genderqueer
Giving Back, One Basketball Court at a Time
When basketball courts end up with cracks, dips and divots, Dan Peterson and company step in. With the help of artists and community volunteers, Project Backboard resurfaces public courts and turns them into fly, large-scale pieces of art. The organization has brought new life and sleek aesthetics to over two dozen basketball courts around the world—including in Dan’s hometown of New Rochelle, New York. #Basketball #Streetart #Courtart #Community #PowerFromPeople #Documentation #Movie
New York 
The City of Time
Among the Jura Mountains in Western Switzerland, just a few miles off the border of France, is a city where time begins. Sitting at the center of an area known as “Watch Valley,” La Chaux-de-Fonds is the beating heart of the Swiss watchmaking industry. Some of the world’s most expensive and renowned brands—including Rolex, Patek Phiippe and Tissot—have workshops in the city that continue to produce intricate, incredibly sought after timepieces. Join us as we meet the artisans keeping Switzerland’s watchmaking legacy forever ticking.

Vimeo: The City of Time (Great Big Story)

#switzerland #Watches #Time #Documentation #Movie


Shareblog !

International Center on Nonviolent Conflict (ICNC).

Pas encore tout épluché, mais ce site semble proposer des articles vraiment intéressants sur la résistance civile, la non-violence, les luttes, actions, mouvements... Bref, une bible ?... ;)

#shareblog #ressources #activisme #résistance-civile #documentation
Resource Library

ICNC: Resource Library | ICNC (tsuperadmin)

- #Documentation for #Public #APIs at the #Internet #Archive

Internet Archive is well-known for our interactive user services. These include the Wayback Machine, the archive.org website, and OpenLibrary. Less well known are the programmatic, or API (Application Program Interface) tools that can allow users and computer programs to access archived information “at scale.”

Etsy’s experiment with immutable documentation

Introduction Writing documentation is like trying to hit a moving target. The way a system works changes constantly, so as soon as you write a piece of documentation for it, it starts to get stale.…

HN Discussion: https://news.ycombinator.com/item?id=18674158
Posted by telotortium (karma: 741)
Post stats: Points: 153 - Comments: 54 - 2018-12-13T17:31:38Z

\#HackerNews #documentation #etsys #experiment #immutable #with
Article content:


Writing documentation is like trying to hit a moving target. The way a system works changes constantly, so as soon as you write a piece of documentation for it, it starts to get stale. And the systems that need docs the most are the ones being actively used and worked on, which are changing the fastest. So the most important docs go stale the fastest! [1]^1

Etsy has been experimenting with a radical new approach: immutable documentation.

Woah, you just got finished talking about how documentation goes stale! So doesn’t that mean you have to update it all the time? How could you make documentation read-only?

How docs go stale

Let’s back up for a sec. When a bit of a documentation page becomes outdated or incorrect, it typically doesn’t invalidate the entire doc (unless the system itself is deprecated). It’s just a part of the doc with a code snippet, say, which is maybe using an outdated syntax for an API.

For example, we have a command-line tool called dbconnectthat lets us query the dev and prod databases from our VMs. Our internal wiki has a doc page that discusses various tools that we use to query the dbs. The part that discusses ‘dbconnect’ goes something like:

Querying the database via dbconnect ... ((section 1)) dbconnect is a script to connect to our databases and query them. [...] ((section 2)) The syntax is: % dbconnect

Section 1 gives context about dbconnect and why it exists, and section 2 gives tactical details of how to use it.

Now say a switch is added so that dbconnect --dev queries the dev db, and dbconnect --prod queries the prod db. Section 2 above now needs to be updated, because it’s using outdated syntax for the dbconnect command. But the contextual description in section 1 is still completely valid. So this doc page is now technically stale as a whole because of section 2, but the narrative in section 1 is still very helpful!

In other words, the parts of the doc that’s most likely to go stale are the tactical, operational details of the system. How to use the system is constantly changing. But the narrative of why the system exists and the context around it is less likely to change quite so quickly.
How to use the system is constantly changing. But the narrative of why the system exists and the context around it is less likely to change quite so quickly.
Docs can be separated into how-docs and why-docs

Put another way: ‘code tells how, docs tell why’ [2]^2. Code is constantly changing, so the more code you put into your docs, the faster they’ll go stale. To codify this further, let’s use the term “how-doc” for operational details like code snippets, and “why-doc” for narrative, contextual descriptions [3]^3. We can mitigate staleness by limiting the amount we mix the how-docs with the why-docs.
We can mitigate staleness by limiting the amount we mix the how-docs with the why-docs.
Documenting a command using Etsy’s FYI system

At Etsy we’ve developed a system for adding how-docs directly from Slack. It’s called “FYI”. The purpose of FYI is to make documenting tactical details — commands to run, syntax details, little helpful tidbits — as frictionless as possible.
FYI is a system for adding how-docs directly from Slack.
Here’s how we’d approach documenting dbconnect using FYIs [4]^4:

Kaley was searching the wiki for how to connect to the dbs from her VM, to no avail. So she asks about it in a Slack channel:

[5]hey @here anyone remember how to connect to the dbs in dev? I forget how. It’s something like dbconnect etsy_shard_001A but that’s not working

When she finds the answer, she adds an FYI using the ?fyi command (using our [6]irccat integration in Slack [7]^5):

[8]?fyi connect to dbs with dbconnect etsy_shard_000_A (replace 000 with the shard number). A or B is the side

Jason sees Kaley add the FYI and mentions you can also use dbconnect to list the databases:

[9]you can also do dbconnect -l to get a list of all DBs/shards/etc, and it works for dev-proxy on or off

Kaley then adds the :fyi: Slack reaction (reacji) to his comment to save it as an FYI:

[10]you can also do dbconnect -l to get a list of all DBs/shards/etc, and it works for dev-proxy on or off

A few weeks later, Paul-Jean uses the FYI query command ?how to search for info on connecting to the databases, and finds Kaley’s FYI [11]^6:

[12]?how database connect

He then looks up FYIs mentioning dbconnect specifically to discover Jason’s follow-up comment:

[13]?how dbconnect

But he notices that the dbconnect command has been changed since Jason’s FYI was added: there is now a switch to specify whether you want dev or prod databases. So he adds another FYI to supplement Jason’s:

[14]?fyi to get a list of all DBs/shards/etc in dev, use dbconnect --dev, and to list prod DBs, use dbconnect --prod (default)

Now ?how dbconnect returns Paul-Jean’s FYI first, and Jason’s second:

[15]?how dbconnect

FYIs trade completeness for freshness

Whenever you do a ?how query, matching FYIs are always returned most recent first. So you can always update how-docs for dbconnect by adding an FYI with the keyword “dbconnect” in it. This is crucial, because it means the freshest docs always rise to the top of search results.

FYIs are immutable, so Paul-Jean doesn’t have to worry about changing any FYIs created by Jason. He just adds them as he thinks of them, and the timestamps determine the priority of the results. How-docs change so quickly, it’s easier to just replace them than try to edit them. So they might as well be immutable.
How-docs change so quickly, it’s easier to just replace them than try to edit them. So they might as well be immutable.
Since every FYI has an explicit timestamp, it’s easy to gauge how current they are relative to API versions, OS updates, and other internal milestones. How-docs are inherently stale, so they might as well have a timestamp showing exactly how stale they are.
How-docs are inherently stale, so they might as well have a timestamp showing exactly how stale they are.
The tradeoff is that FYIs are just short snippets. There’s no room in an FYI to add much context. In other words, FYIs mitigate staleness by trading completeness for freshness.
FYIs mitigate staleness by trading completeness for freshness
Since FYIs lack context, there’s still a need for why-docs (eg a wiki page) about connecting to dev/prod dbs, which mentions the dbconnect command along with other relevant resources. But if the how-docs are largely left in FYIs, those why-docs are less likely to go stale.

So FYIs allow us to decouple how-docs from why-docs. The tactical details are probably what you want in a hurry. The narrative around them is something you sit back and read on a wiki page.
FYIs allow us to decouple how-docs from why-docs
What FYIs are

To summarize, FYIs are:
\* How-docs: code snippets, API details, or helpful tips that explain how to use a system
\* Fresh: searching FYIs gives most recent matches first, and adding them is easy
\* Time-stamped: every FYI has an explicit timestamp, so you know exactly how stale it is
\* Immutable: instead of editing an FYI you just add another one with more info
\* Discoverable: using the  ?how command
\* Short: about the length of a sentence
\* Unstructured: just freeform text
\* Collaborative: FYIs quickly share knowledge within or across teams
\* Immediate: use  ?fyi  or just tag a slack message with the  :fyi: reaction

What FYIs are NOT

Similarly, FYIs are NOT:
\* Why-docs: FYIs are short, helpful tidbits, not overviews, prose or narratives
\* Wiki pages or READMEs: why-docs belong on the wiki or in READMEs
\* Code comments: a code comment explains what your code does better than any doc


Etsy has recognized that technical documentation is a mixture of two distinct types: a narrative that explains why a system exists (“why-docs”), and operational details that describe how to use the system (“how-docs”). In trying to overcome the problem of staleness, the crucial observation is that how-docs typically change faster than why-docs do. Therefore the more how-docs are mixed in with why-docs in a doc page, the more likely the page is to go stale.

We’ve leveraged this observation by creating an entirely separate system to hold our how-docs. The FYI system simply allows us to save Slack messages to a persistent data store. When someone posts a useful bit of documentation in a Slack channel, we tag it with the :fyi: reacji to save it as a how-doc. We then search our how-docs directly from Slack using a bot command called ?how.

FYIs are immutable: to update them, we simply add another FYI that is more timely and correct. Since FYIs don’t need to contain narrative, they’re easy to add, and easy to update. The ?how command always returns more recent FYIs first, so fresher matches always have higher priority. In this way, the FYI system combats documentation staleness by trading completeness for freshness.

We believe the separation of operational details from contextual narrative is a useful idea that can be used for documenting all kinds of systems. We’d love to hear how you feel about it! And we’re excited to hear about what tooling you’ve built to make documentation better in your organization. Please get in touch and share what you’ve learned. Documentation is hard! Let’s make it better!


The FYI system was designed and implemented by Etsy’s FYI Working Group: Paul-Jean Letourneau, Brad Greenlee, Eleonora Zorzi, Rachel Hsiung, Keyur Govande, and Alec Malstrom. Special thanks to Mike Lang, Rafe Colburn, Sarah Marx, Doug Hudson, and Allison McKnight for their valuable feedback on this post.


1. From [16]“The Golden Rules of Code Documentation”: “It is almost impossible without an extreme amount of discipline, to keep external documentation in-sync with the actual code and/or API.”
2. Derived from “code tells what, docs tell why” in [17]this HackerNoon post.
3. The similarity of the terms “how-doc” and “why-doc” to the term [18]here-doc is intentional. For any given command, a here-doc is used to send data into the command in-place, how-docs are a way to document how to use the command, and why-docs are a description of why the command exists to begin with.
4. You can replicate the FYI system with any method that allows you save Slack messages to a predefined, searchable location. So for example, one could simply install the [19]Reacji Channeler bot, which lets you assign a Slack reacji of your choosing to cause the message to be copied to a given channel. So you could assign an “fyi” reacji to a new channel called “#fyi”, for example. Then to search your FYIs, you would simply go to the #fyi channel and search the messages there using the Slack search box.
5. When the :fyi: reacji is added to a Slack message (or the ?fyi irccat command is used), an [20]outgoing webhook sends a POST request to irccat.etsy.com with the message details. This triggers a PHP script to save the message text to a SQLite database, and sends an acknowledgement back to the Slack [21]incoming webhook endpoint. The acknowledgement says “OK! Added your FYI”, so the user knows their FYI has been successfully added to the database.
6. Searching FYIs using the ?how command uses the same architecture as for adding an FYI, except the PHP script queries the SQLite table, which supports full-text search via the [22]FTS plugin.


Visible links
1. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref1
2. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref2
3. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref3
4. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref4
5. https://codeascraft.com/wp-content/uploads/2018/10/image3-1.png
6. https://github.com/RJ/irccat
7. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref5
8. https://codeascraft.com/wp-content/uploads/2018/10/image9-1.png
9. https://codeascraft.com/wp-content/uploads/2018/10/image5-1.png
10. https://codeascraft.com/wp-content/uploads/2018/10/image13.png
11. https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/#ref6
12. https://codeascraft.com/wp-content/uploads/2018/10/image14.png
13. https://codeascraft.com/wp-content/uploads/2018/10/image2-1.png
14. https://codeascraft.com/wp-content/uploads/2018/10/image10-1.png
15. https://codeascraft.com/wp-content/uploads/2018/10/how-dbconnect.jpeg
16. https://blog.jooq.org/2013/02/26/the-golden-rules-of-code-documentation/
17. https://hackernoon.com/write-good-documentation-6caffb9082b4
18. https://www.tldp.org/LDP/abs/html/here-docs.html
19. https://get.slack.help/hc/en-us/articles/360000482666-Copy-messages-to-another-channel-instantly
20. https://api.slack.com/custom-integrations/outgoing-webhooks
21. https://api.slack.com/custom-integrations/incoming-webhooks
22. https://www.sqlite.org/fts3.html

HackerNewsBot debug: Calculated post rank: 120 - Loop: 467 - Rank min: 100 - Author rank: 38
Etsy’s experiment with immutable documentation
newer older