Showing posts with label doc'ing. Show all posts
Showing posts with label doc'ing. Show all posts

2022-11-19

The Art Of Note Taking by Thinknetic.net 2022

 22.11.19: bk.adds/doc/Thinknetic 2022`The Art Of Note Taking: 

. this is a brief review of the book:

Thinknetic 2022`The Art Of Note Taking: 

Your Research-Based Guide To Taking Notes That Will Stick To Your Memory

https://amzn.to/3GwIYFE[ad]

. the writer is Dianna Aquino,

a teacher with a doctorate, who was an honor student.

. the thinknetic.net founder is Michael Meisner.

5-star/surprised by benefits of handwriting:

2017-11-24

Intel's lack of documentation stalled MINIX

11.21: news.cyb/adds/doc/Intel's lack of documentation stalled MINIX:
. in an IEEE Computer interview,
[ieeeComputerSociety 2014]
Tanenbaum revealed he designed MINIX when
AT&T closed the source for Unix Version 7
and they could no longer use it
when teaching about the design of an OS.
. but it kept crashing until he heard a rumor
(nothing in the documentation mentioned it)
that the Intel chip when overheating
was causing an interrupt 15.
If his student Robert hadn't revealed the interrupt,
"there would have been no MINIX" he said.

2014-12-14

religious science

4.8: adds/doc'ing/religious science:
. I was wondering how the early church decided
which texts to include in the bible;
it seems that after reading them all,
they developed a theory for what most likely happened,
and then included only texts that agreed with that theory .
. so their bible really has become
the early church's theory of Jesus .
. what is needed by good documentation
is a metabible,
that summarizes all the original documents
and why a particular theory would treat that document .
. each document's summary would mention
what other documents it contradicted,
and would offer various theories about
who the authors are and what their motive was .

2013-12-25

design by autocrat

11.20:  addx/design by autocrat:
. what if you are deluded, and need others' help
to show you that your design is fundamentally flawed;
but you are drugged by the freedom of working alone?
well, I've wanted to reuse some other work
but I've often found the documentation unreadable,
so this is about building an understanding
through finding that my design was flawed .
. at least I will be on the step toward
both designing a program I like,
and writing some documentation I can read
(likely others can read it too,
because I'm very forgetful,
so I will need to be thorough).

2013-03-31

pythonic software construction

2.2: news.addx/pythonic software construction:

Fred Brooks` Mythical Man Month:
. Brooks suggested we plan to throw one away
because we will throw the first attempt anyway;
10years later he noted that incremental development
can reduce much of that loss;
nevertheless,
what he said still applies on a smaller scale:

2012-08-23

lang's should document pragmatics

7.21: adda/doc's/intended use as related to resources used:
. here is part of Python's Recommendations
for a library's coding style:
"( Code should be written in a way that
does not disadvantage an implementation of Python
For example, CPython's a += b or a = a + b
is an efficient implementation of
in-place string concatenation;
but in Jython,
the ''.join() form should be used instead.
This will ensure that concatenation occurs in
linear time across various implementations.)
[ie, jython is about java is about oop;
and if you have something like
( a = a op x ) to say in {oop, java, jython}
the oop way to do that is a.op(x)
and if you're a big oop fan and said
( a = b op x )
it's assumed you would never do so for
the case where (a) is the same as (b) .]
--
. this reminded me that part of
documenting a language
should be not only what the resource usage is,
but also the intended application;
ie, it should warn you if it's
not the most efficient way to do something
and point you to what is .

2012-05-13

college attracts female software engineers

4.3: news.cyb/dev.py/
college attracts female software engineers:

. after switching to an easy programming language
(going from Java to Python)
Mudd college is attracting many more females
into their computer science programs .
David MacQuigg:
edu-sig@python.org/transforming CS at Harvey Mudd/5:40 PM:
Excellent article.  It is good to see the revolution
moving forward in at least a few schools.
Khan Academy is also adding CS.
This is very encouraging.
When I read the headline
"Giving Women the Access Code",
I was worried that it sounded like a
watered-down course for women.
It's not that at all.
It's the guys that need to change their attitude.
When I see our introductory class
with 220 freshmen in a course on C,
2/3 of whom will be "washed out" by next year,
I wonder how many of them will go on to be
leaders in law, politics, even technology.
What will be the impact of their lack of
understanding or appreciation of what us techies do.
It's no wonder engineers are not even in the room
when important decisions are made.
my response:
. the article he refers to said women got interested
in a computer science program
after the program shifted its focus:
"(. this course isn't about wrestling with
monster languages like Java or C;
we use an easy language like Python
so you can get on with what's important:
getting your machine to do more of your job .)
I think he goes on to say:
. so many of tomorrow's leaders
are being put off by the monster languages;
and, they are destined thereafter to have
little understanding or appreciation
of what techies[automators] do.
(make the world a more efficient place).
. engineers are not invited to requirements meetings?
I don't think it's because of a lack of
understanding or appreciation of what techies do;
rather, the psychology of leadership
includes something like computer science's
Principle of Least Priviledge:
the safest and simplest way to conduct business
is to develop modules with clean, minimal interfaces:
that means interfaces that don't include
inputs a module doesn't need .
. engineers may prefer having a say in their job,
but an engineer's performance should not require that,
unless it's a very new technology,
in which case the mgt has no idea what is possible
without the engineer's input .
. what's missing from an optimal world
is making everyone fluent in their ability to
automate or precisely document their job;
and, I think moving to Python
is a step in the right direction .

2010-06-30

adda keeping things documented

6.4: adda/syntax decl's for freedom with readability:
. as much as possible, the code should be
readable from just knowing english and math;
that means,
that if you want to do strange things like
,() = (,,,)
then you need to describe that in a
syntax declaration, something at the top of
every source file [6.30:
though it could by pointer,
and then the code reader would auto'ly
expand all such pointers .]

6.20: adda/monkey patch vs freedom:
. after learning of "(monkey patch),
the place to be is full documentation:
if there are any ways that relinking
can modify a given package,
the state of current linkage needs to be
readable as part of the source,
so that linkage changes show up as
a modification to the package .


2010-05-18

search function for google'knol

4.27: web.addn`gear/net.knol/search:

. google custom search; is it for knol?
google'cse (custom search engine):
doshdosh.com shows how to use it on your site:

. however, if your site is on knol,
do an author-specific knol'search:
. put a link on your page entitled:
[search my knol pages]
and link it to here(example my= philip-torrance's).

. this works much better than
google(site:knol.google.com/k/philip-torrance)
because that search misses some main content pages
and it links to many unrelated words
just because they are showing up in the side bar
which contains unrelated or duplicate trivia
by listing other pages by this author .

. there's an api for custom search:
[5.18: todo:
. could this be used for improving a knol search?]

2010-03-31

the whole truth

3.19: adds/the whole truth:
. the whole truth, nothing but the truth,
and easy to access:
. contrasting given info with
any popular myths it contradicts
(making sure intended overwrites
are not merely appended in reader's mind).
. pointing out how the given info
when known by you
will add value for us .
(the free capitalist principle) .

2009-12-31

real sensitivity training

11.10: psy/real sensitivity training:
. I've often been perplexed at attempts by policy
to replace terms like "(the retarded)
with "(the learning challenged);
that change might have less sour memories
than anything like "(retard)
but, it is still pointing at the same class
using a different name;
ie, after a while, they will just have to
change that name too
as soon as "(the learning challenged) learn to
associate that name
with the way staff treats them or points at them .
. one real difference that policy could make
is to refer to people by their effect on others:
eg, the real issue with referring to "(the retarded)
is that the enclosing situation is sensitive to
those who are irrational, violent, protection-needy,
unsociable, or uncooperative;
and, accident-prone, or future-blind, etc .
. these are the important differences
that characterize class we are pointing at,
yet they all traits that
the clients could equally say of staff;
and, these terms of affect
place a healthy emphasis on
where you are
rather than how you got there .


11.15: pol/mongoloids, and nobody even cared:
. recalled being informed that the term "(hispanic)
is like "(mongoloid):
you don't refer to people by where they're from
because that's a baseless discriminant
since you can't draw any relevant conclusions
from just knowing where someone's ancestors were from .
. yes, and now it seems funny using mongoloid as a
euphamism for downs syndrome
since the notable feature of that disorder
is not appearing to be from mongolia
but being prone to irrational or even violent acts .
. actually the ancestors of mongolia were indeed known for
unparalleled ferocious acts of violence .
. now I see the satire of that 1980's song
with the urgent rock beat, and these lyrics:
"(
. mongoloid, he was mongoloid, and nobody even cared!
)
. the whole world is based on so much irrationality
but is backing it up with ferocious acts of violence,
and nobody gives it a second thought !
[ . to give myself as example,
I'm a livid advocate of pro-choice and death-with-dignity
but my real problem is not having more control over
reproductive machinery,
assignment of careprovider responsibilities,
and drugs that make pain worth living .
] .

2009-12-30

terminology

11.30: web.adds/engl/a word for study of sensible terminology:

. instead of the word "(engl),
I was hoping for a replacement that meant
study and design of sensible terminology .

Etymology
. the derivation of a word.
2. an account of the history of a particular word or element of a word.
3. the study of historical linguistic change,
esp. as manifested in individual words.
Origin:

1398, from Gk. etymologia, from etymon "true sense"
(neut. of etymos "true," related to eteos "true")
+ logos "word." In classical times, of meanings; later, of histories.
Latinized by Cicero as veriloquium.
1350Ð1400; ME: L etymologia: Gk etymolog’a,
equiv. to etymol—g(os) studying the true meanings and values of words
(Žtymo(s) true (see etymon ) + l—gos word, reason) + -ia -y 3


lexis:
1955Ð60; : Gk lŽxis speech, diction, word, text,
equiv. to lŽg(ein) to speak, recount
(akin to l—gos account, word, L legere to read;
see logos, lection ) + -sis -sis
the vocabulary of a language, as distinct from its grammar;
the total stock of words and idiomatic combinations of them in a language;
lexicon.

lexigram:
a symbol that represents a word
lexicology:
The branch of linguistics that deals with the lexical component of language.
study of the formation, meaning, and use of words
and of idiomatic combinations of words.

lexicography:
1. the writing, editing, or compiling of dictionaries.
2. the principles and procedures involved in
writing, editing, or compiling dictionaries.

lexicon (plural: lexica):
a wordbook or dictionary, esp. of Greek, Latin, or Hebrew.
2. the vocabulary of a particular language, field, social class, person, etc.
3. inventory or record
4. Linguistics.
a. the total inventory of morphemes in a given language.
b. the inventory of base morphemes plus their combinations with derivational morphemes.

lexical:
1. of or pertaining to the words or vocabulary of a language,
esp. as distinguished from its grammatical and syntactical aspects.
2. of, pertaining to, or of the nature of a lexicon.

lexeme:
n. The fundamental unit of the lexicon of a language.
Find, finds, found, and finding are forms of the English lexeme find.

2009-12-28

quality documentation

9.6: news.addx/doc's/good examples:
. according to Xah Lee
here are doc's that co.python's should emulate:
. it seems to be the oss`culture,
-- Perl, Python, Unix, Apache etc[in the unix anti-cs spirit] --
that their documentation exhibit
jargon abuse, rambling, author [self-promotion], or hodgepodge
but this doesn't apply to Gnu's Not Unix project.
GNU docs are geeky in comparison to the above commercial docs;
but, the GNU project in general (gnupress.org)
.


10.9: adda/doc files:
. instead of having long comments,
have in addition to head and body files
a doc file that includes docs for that unit
wherein you redo the routine in english (your own words) .